# AGENT
Source: https://docs.x.com/AGENT



# 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](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](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](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/enterprise-api/llms.txt)
     * [https://docs.x.com/x-ads-api/llms.txt](https://docs.x.com/x-ads-api/llms.txt)
     * [https://docs.x.com/xdks/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](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](https://docs.x.com/tools/mcp) — Hosted X MCP (`api.x.com/mcp` via `xurl`) + documentation search MCP.

5. **skill.md** (capability summary)
   * [https://docs.x.com/skill.md](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](https://docs.x.com/openapi.json) (or [https://api.x.com/2/openapi.json](https://api.x.com/2/openapi.json))
* Changelog: [https://docs.x.com/changelog.md](https://docs.x.com/changelog.md) (RSS feed: [https://docs.x.com/changelog/rss.xml](https://docs.x.com/changelog/rss.xml))
* Status page: [https://developer.x.com/status](https://developer.x.com/status) (incident history: [https://docs.x.com/incidents.md](https://docs.x.com/incidents.md))
* Developer Guidelines: [https://docs.x.com/developer-guidelines.md](https://docs.x.com/developer-guidelines.md)
* Support & Community: [https://devcommunity.x.com](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.


# AGENTS
Source: https://docs.x.com/AGENTS



# 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](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](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](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/enterprise-api/llms.txt)
     * [https://docs.x.com/x-ads-api/llms.txt](https://docs.x.com/x-ads-api/llms.txt)
     * [https://docs.x.com/xdks/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](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](https://docs.x.com/tools/mcp) — Hosted X MCP (`api.x.com/mcp` via `xurl`) + documentation search MCP.

5. **skill.md** (capability summary)
   * [https://docs.x.com/skill.md](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](https://docs.x.com/openapi.json) (or [https://api.x.com/2/openapi.json](https://api.x.com/2/openapi.json))
* Changelog: [https://docs.x.com/changelog.md](https://docs.x.com/changelog.md) (RSS feed: [https://docs.x.com/changelog/rss.xml](https://docs.x.com/changelog/rss.xml))
* Status page: [https://developer.x.com/status](https://developer.x.com/status) (incident history: [https://docs.x.com/incidents.md](https://docs.x.com/incidents.md))
* Developer Guidelines: [https://docs.x.com/developer-guidelines.md](https://docs.x.com/developer-guidelines.md)
* Support & Community: [https://devcommunity.x.com](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.


# X API changelog and release notes
Source: https://docs.x.com/changelog

Release notes and version history for the X API v2, Enterprise APIs, Ads API, SDKs, streaming, webhooks, and the developer platform.

To subscribe to updates, please [**“Turn on notifications”**](https://help.x.com/en/managing-your-account/notifications-on-mobile-devices#:~:text=In%20the%20top%20menu,%20you,you%20would%20like%20to%20receive) for [**@API**](https://x.com/api). You can also follow this changelog in your feed reader via the [**RSS feed**](https://docs.x.com/changelog/rss.xml).

<Update label="Aug 13, 2026" description="X Ads API">
  ### Updated `video_total_views` definition

  We updated the definition of the `video_total_views` metric in the `VIDEO` metrics group of the [X Ads API Analytics endpoints](/x-ads-api/analytics). It now reports views that are 100% in-view for at least 3 seconds, plus any view where a user manually clicks the play button.

  The previous definition (at least 50% in-view for 2 seconds, per the MRC standard) no longer applies. The prior "100% in-view for 3 seconds" definition remains available as the `video_3s100pct_views` metric, and you can continue bidding on it via the `VIEW_3S_100PCT` bid unit.
</Update>

<Update label="Jul 21, 2026" description="X API v2">
  ### Mute and block events for X Activity API

  Today, we added mute and block events to the [X Activity API](https://docs.x.com/x-api/activity/introduction). You can now subscribe by User ID to receive real-time notifications when a user mutes or unmutes (`mute.mute`, `mute.unmute`) or blocks or unblocks (`block.block`, `block.unblock`) another user.

  These are private events: they require user-context (OAuth 2.0) authentication with the `mute.read` or `block.read` scope, respectively, and the `user_id` filter matches the user performing the action.
</Update>

<Update label="Jun 11, 2026" description="X API v2">
  ### Articles draft and publish endpoints

  Today, we added [new endpoints](/x-api/articles/introduction) for drafting and publishing Articles via the X API.
</Update>

<Update label="Jun 4, 2026" description="X API v2">
  ### Post create and delete events for X Activity API

  Today, we added `post.create` and `post.delete` events to the [X Activity API](https://docs.x.com/x-api/activity/introduction). You can now subscribe by User ID to receive real-time notifications when a user creates or deletes a Post.

  For basic per-user post activity, use XAA. For advanced keyword filtering and the full set of Filtered Stream operators, continue to use the [Filtered Stream](/x-api/posts/filtered-stream/introduction).
</Update>

<Update label="Jun 3, 2026" description="X API v2">
  ### `paid_partnership` Post field

  Added support for the `paid_partnership` field on Posts.

  * When creating a Post via `POST /2/tweets`, set `"paid_partnership": true` to indicate the Post is a paid partnership (i.e., the author is disclosing that it contains paid promotion). The Post will be labeled as a paid promotion.
  * When reading Posts, request `tweet.fields=paid_partnership` to retrieve the value (`true` if the author has disclosed the Post as containing paid promotion).
</Update>

<Update label="May 4, 2026" description="X API v2">
  ### Search endpoints migrating to new search index

  Today, we migrated the X API v2 search endpoints (`/2/tweets/search/recent`, `/2/tweets/search/all`, `/2/tweets/counts/recent`, `/2/tweets/counts/all`) to the new X core platform search index. This brings major performance improvements, dramatically fewer 503 errors, and three new precision operators: `min\_likes:`, `min\_replies:`, and `min\_reposts:`. Note: retweets are no longer returned in keyword-based search results (the Filtered Stream is unchanged). Learn more [here](https://devcommunity.x.com/t/important-update-x-api-search-endpoints-migrating-to-new-search-index/264595).
</Update>

<Update label="Apr 16, 2026" description="X API">
  ### X API pricing update: Owned Reads now \$0.001

  Effective April 20, 2026, we introduced new **"Owned Reads"** pricing at **\$0.001** per resource (1,000 for **\$1**) for qualifying endpoints when accessing your own data:\
  `GET /2/users/{id}/bookmarks`, `/blocking`, `/muting`, `/pinned_lists`, `/tweets`, `/mentions`, `/liked_tweets`, `/followers`, `/following`, `/owned_lists`, `/followed_lists`, and `/list_memberships`.

  We also updated writes — `POST /2/tweets` is now **\$0.015** per post, and Posts containing a URL are **\$0.20** per Post (summoned replies remain **\$0.01**).

  Following, Likes, and Quote-Posts via the API have been removed from all self-serve tiers.

  Learn more [here](https://devcommunity.x.com/t/x-api-pricing-update-owned-reads-now-0-001-other-changes-effective-april-20-2026/263025).
</Update>

<Update label="Mar 20, 2026" description="X API v2">
  ### Deprecation of Account Activity replay endpoint

  Today, we announced the deprecation of `POST /2/account_activity/replay/webhooks/{webhook_id}/subscriptions/all`, effective March 25, 2026 at 12:00 PM ET. Use the new consolidated `POST /2/webhooks/replay` endpoint instead — it provides identical functionality. Learn more [here](https://devcommunity.x.com/t/deprecation-of-account-activity-replay-endpoint/260354).
</Update>

<Update label="Mar 18, 2026" description="X API v2">
  ### Direction filter for X Activity API subscriptions

  Today, we added an optional `direction` filter to X Activity API subscriptions. Subscribers can now scope DM and chat events to `sent`, `received`, or both, reducing noise when only outgoing or incoming events are needed.
</Update>

<Update label="Mar 13, 2026" description="X API v2">
  ### Updates to event types format in the X Activity API

  Today, we announced changes to event type naming in the X Activity API, effective March 18, 2026. PascalCase event types (e.g., `ProfileBioUpdate`) are being deprecated in favor of a dot-separated lowercase format (e.g., `profile.update.bio`). Update any filtering, switch statements, or deserialization logic that relies on the old values. Learn more [here](https://devcommunity.x.com/t/updates-to-event-types-format-in-the-x-activity-api/259765).
</Update>

<Update label="Mar 11, 2026" description="X API v2">
  ### Legacy Direct Message events in the X Activity API

  Today, we added legacy DM events (`dm.received`, `dm.sent`, `dm.read`, `dm.indicate_typing`) to the [X Activity API](https://docs.x.com/x-api/activity/introduction). This brings DM event delivery from the Account Activity API into the lower-latency XAA pipeline.
</Update>

<Update label="Feb 23, 2026" description="X API v2">
  ### Addressing LLM-generated spam

  Today, we made changes to reduce automated, low-quality replies on X. Programmatic replies via `POST /2/tweets` are now only permitted when the original Post's author has "summoned" the replier (by @mentioning that account or quoting one of its Posts). Additional restrictions apply to programmatically @mentioning or quoting users. These changes affect self-serve tiers only — Enterprise access is not impacted. Learn more [here](https://devcommunity.x.com/t/x-api-v2-update-addressing-llm-generated-spam/257909).
</Update>

<Update label="Feb 6, 2026" description="X API">
  ### Launch of X API Pay-Per-Use pricing

  Today, we officially launched **X API Pay-Per-Use** pricing — a flexible credit-based model built for indie builders, startups, and hobbyists. Highlights:

  * A new Developer Console at [console.x.com](https://console.x.com)
  * The [XDK (X Developer Kit)](https://docs.x.com/xdks/overview) with first-party Python and TypeScript SDKs
  * An interactive [Playground](https://github.com/xdevplatform/playground) for testing
  * An [MCP server](https://github.com/xdevplatform/xmcp) for AI models
  * Earn up to **20% back in xAI/Grok API credits** on every dollar spent on the X API

  Public Utility Apps continue to receive free scaled access. Recently active Legacy Free tier users receive a one-time \$10 voucher. Basic and Pro plans remain available, and existing subscribers can opt in to Pay-Per-Use. Learn more [here](https://devcommunity.x.com/t/announcing-the-launch-of-x-api-pay-per-use-pricing/256476).
</Update>

<Update label="Jan 28, 2026" description="X API v2">
  ### Spaces events in the X Activity API

  Today, we added Spaces lifecycle events (`spaces.start`, `spaces.end`) to the [X Activity API](https://docs.x.com/x-api/activity/introduction). Subscribe by User ID to be notified in real time when a Space starts or ends.
</Update>

<Update label="Jan 19, 2026" description="X API v2">
  ### Deprecating count-based operators

  Today, we deprecated the `min\_likes`, `min\_replies`, and `min\_reposts` operators on `/2/tweets/search/recent` and `/2/tweets/search/all`. This change does not affect the equivalent operators in the Filtered Stream. We are evaluating how to best re-enable these in the future. Learn more [here](https://devcommunity.x.com/t/deprecating-count-based-operators-in-the-x-api/254933).
</Update>

<Update label="Jan 15, 2026" description="X API v2">
  ### OAuth 2.0 support added to Account Activity API v2

  Today, we added full OAuth 2.0 support to the [Account Activity API v2](https://docs.x.com/x-api/account-activity/introduction). Developers can now create subscriptions using OAuth 2.0 with fine-grained scopes (e.g., `follow.read`) instead of the all-or-nothing OAuth 1.0a permission model. Existing OAuth 1.0a-based integrations continue to work without disruption — when present, OAuth 1.0a permissions fully override OAuth 2.0 scopes. Learn more [here](https://devcommunity.x.com/t/announcement-oauth2-0-support-added-to-account-activity-api-v2/254633).
</Update>

<Update label="Dec 23, 2025" description="X API">
  ### Introducing X API Playground

  Today, we introduced the [X API Playground](https://github.com/xdevplatform/playground) — a self-hosted local server that emulates X API v2 endpoints. Develop and test integrations without making real API calls or hitting rate limits. Includes realistic mock data, state persistence, OpenAPI validation, rate-limit simulation, and a web UI. Install with `go install github.com/xdevplatform/playground/cmd/playground@latest`. Learn more [here](https://devcommunity.x.com/t/introducing-x-api-playground-local-development-tool-for-x-api-v2/253442).
</Update>

<Update label="Nov 19, 2025" description="X API v2">
  ### Launch of news endpoints

  Today, we launched the new [News endpoints](https://docs.x.com/x-api/news/introduction) in the X API v2:

  * `GET /2/news/search` — returns trending news stories matching a search query
  * `GET /2/news/{id}` — looks up a specific news story by ID

  Both endpoints support `news.fields` for selecting fields like `name`, `summary`, `contexts`, `cluster\_posts\_results`, and `last\_updated\_at\_ms`. Learn more [here](https://devcommunity.x.com/t/announcing-the-news-endpoints-in-the-x-api-v2/251833).
</Update>

<Update label="Nov 3, 2025" description="X API v2">
  ### Launch of the Python and TypeScript XDKs

  Today, we launched the official first-party [Python](https://docs.x.com/xdks/python/overview) and [TypeScript](https://docs.x.com/xdks/typescript/overview) XDKs (X Developer Kits) for the X API v2. The XDKs handle authentication (Bearer Token, OAuth 2.0 PKCE, OAuth 1.0a), automatic pagination, real-time streaming with reconnect handling, and comprehensive coverage of all v2 endpoints. Install with `pip install xdk` or `npm install @xdevplatform/xdk`. Learn more [here](https://devcommunity.x.com/t/announcing-the-python-and-typescript-xdks-for-the-x-api-v2/250860).
</Update>

<Update label="Oct 27, 2025" description="X API v2">
  ### Keyword filtering for X Activity API subscriptions

  Today, we added keyword filtering to X Activity API subscriptions. In addition to filtering by User ID, subscribers can now narrow event delivery further by keyword — useful for News events and other event types where high event volumes warrant additional filtering.
</Update>

<Update label="Oct 24, 2025" description="X API v2">
  ### Verified badge, affiliate badge, and handle update events in the X Activity API

  Today, we expanded the [X Activity API](https://docs.x.com/x-api/activity/introduction) to deliver additional profile-related event types:

  * `profile.update.verified` — when a user's verification status changes
  * `profile.update.affiliate` — when a user's affiliate badge changes
  * `profile.update.screenname` — when a user changes their @handle
</Update>

<Update label="Oct 20, 2025" description="X API">
  ### X API Pay-Per-Use pricing pilot

  Today, we announced a limited closed pilot for a new credit-based, usage-based pricing model. Developers buy credits upfront and are charged per request — no fixed subscription fees and no monthly object caps. Initial pilot rates: $0.005/Post Read, $0.01/User Read, $0.01/DM Event Read, $0.01/Content Create, $0.01/DM Interaction, $0.015/User Interaction. Learn more [here](https://devcommunity.x.com/t/announcing-the-x-api-pay-per-use-pricing-pilot/250253).
</Update>

<Update label="Oct 18, 2025" description="X API v2">
  ### Launch of the X Activity API open beta

  Today, we launched the open beta of the [X Activity API](https://docs.x.com/x-api/activity/introduction) — a new suite of endpoints for subscribing to real-time activity events on X with sub-second latency. Subscribe to profile event types (`ProfileBioUpdate`, `ProfilePictureUpdate`, `ProfileBannerUpdate`, `ProfileGeoUpdate`, `ProfileUrlUpdate`), filter by User ID, and receive matching events via persistent HTTP stream (`GET /2/activity/stream`) or webhooks. Subscriptions are managed via `POST /2/activity/subscriptions`. Learn more [here](https://devcommunity.x.com/t/announcing-the-x-activity-api-open-beta/250099).
</Update>

<Update label="Oct 3, 2025" description="X API v2">
  ### Post editing via the X API

  Today, we launched the ability to programmatically edit recent Posts via the X API. Use the existing `POST /2/posts` endpoint with a new `edit_options` object containing `previous_post_id`. Requirements: the authenticated user must have X Premium, the Post must be your own, and it must have been created within the last hour. See the updated [Create or Edit Post](https://docs.x.com/x-api/posts/create-post) docs. Learn more [here](https://devcommunity.x.com/t/announcing-post-editing-via-the-x-api/249534).
</Update>

<Update label="Sep 19, 2025" description="X API v2">
  ### Connections API for managing active streaming connections

  Today, we launched the [Connections API](https://docs.x.com/x-api/connections/introduction) for managing active streaming connections programmatically:

  * `GET /2/connections` — list active and historical streaming connections
  * `DELETE /2/connections/all` — terminate all active streaming connections for the app
  * `DELETE /2/connections/{endpoint_id}` — terminate connections for a specific streaming endpoint
  * `DELETE /2/connections` — terminate specific connections by UUID

  This helps developers resolve "TooManyConnections" errors and clean up stale connections without waiting for timeouts.
</Update>

<Update label="Sep 17, 2025" description="X API v2">
  ### Community Notes: evaluate note endpoint

  Today, we added the `POST /2/evaluate_note` endpoint to the [Community Notes API](https://docs.x.com/x-api/community-notes/introduction). AI Note Writers can now evaluate a drafted note before submission to receive signals about its potential helpfulness, claim/opinion alignment, and other model feedback.
</Update>

<Update label="Sep 9, 2025" description="X API v2">
  ### Launch of the Filtered Stream Webhooks API

  Today, we launched the [Filtered Stream Webhooks API](https://docs.x.com/x-api/webhooks/stream/introduction), which delivers matching public Posts asynchronously to a registered webhook instead of requiring a persistent connection. Rules are managed using the existing `/2/tweets/search/stream/rules` endpoints, and matching Posts (including edit history) are delivered as JSON to your webhook. Available to Enterprise developers; supports 25,000+ rules per project with rules up to 2,048 characters. Learn more [here](https://devcommunity.x.com/t/announcing-the-filtered-stream-webhooks-api/248464).
</Update>

<Update label="Aug 22, 2025" description="X API v2">
  ### Removal of like and follow endpoints from Free tier

  To combat abuse, platform manipulation, and fake engagement, we removed `POST /2/users/:id/likes` and `POST /2/users/:id/following` from the X API Free tier, effective immediately. Paid tiers (Basic, Pro, Enterprise) are unaffected. Learn more [here](https://devcommunity.x.com/t/update-to-x-api-free-tier-removal-of-like-and-follow-endpoints/247646).
</Update>

<Update label="Aug 6, 2025" description="X API v2">
  ### PowerStream rules lookup endpoint

  Today, we added the `GET /2/powerstream/rules` endpoint, allowing PowerStream customers to programmatically retrieve the rules configured against their PowerStream instances.
</Update>

<Update label="Jul 28, 2025" description="X API v2">
  ### Broadcasting community posts via `share_with_followers`

  Today, we added a new optional `share_with_followers` boolean parameter to `POST /2/tweets`. When posting with a `community_id` and `share_with_followers: true`, the community Post is also broadcast to the authenticated user's followers' timelines — matching the "Also share with followers" checkbox on x.com.
</Update>

<Update label="Jul 8, 2025" description="X API v2">
  ### Launch of the Community Notes API

  Today, we launched the [Community Notes API](https://docs.x.com/x-api/community-notes/introduction) — a new suite of endpoints for AI Note Writers to programmatically participate in Community Notes:

  * `GET /2/notes/search/posts_eligible_for_notes` — search Posts eligible to receive a Community Note
  * `GET /2/notes/search/notes_written` — retrieve notes previously written by the authenticated AI Note Writer
  * `POST /2/notes` — submit a Community Note

  Access requires X Developer AI enrollment and Community Notes AI Note Writer approval.
</Update>

<Update label="Jun 3, 2025" description="X API">
  ### Change to DM events behavior

  Today, we made a change to X API V2 DM Events behavior. With the new change participant\_ids array will only be included for ParticipantsJoin and ParticipantsLeave events, and it will list only the participants who joined or left at the time of the event. The MessageCreate event will no longer include the participant\_ids array. Learn more [here](https://devcommunity.x.com/t/upcoming-change-to-x-api-dm-events-endpoints-behavior/241841).
</Update>

<Update label="May 20, 2025" description="X API">
  ### Launch of Account Activity API endpoints

  Today, we launched new X API v2 [Account Activity API endpoints](/x-api/webhooks/introduction). Learn more [here](https://devcommunity.x.com/t/account-activity-api-is-now-available-in-v2/242895).
</Update>

<Update label="Apr 30, 2025" description="X API">
  ### Improvements to media upload endpoint

  We made a few improvements to media upload endpoint to improve the developer experience. We introduced Dedicated Endpoints for Chunked Media Upload [Media Upload endpoints](/x-api/media/introduction). Learn more [here](https://devcommunity.x.com/t/media-upload-endpoints-update-and-extended-migration-deadline/241818).
</Update>

<Update label="Apr 3, 2025" description="X API">
  ### Support for email address retrieval with OAuth 2.0

  Today, we added support for email address retrieval with OAuth 2.0 in X API V2. Learn more [here](https://devcommunity.x.com/t/announcing-support-for-email-address-retrieval-with-oauth-2-0-in-the-x-api-v2/240555).
</Update>

<Update label="Feb 18, 2025" description="X API">
  ### Changes to user affiliation data

  Today, we made changes to X API V2 User Affiliation Data. With the new change affiliation.user\_id will return an array of user\_ids. Earlier it used to return a single user\_id as a string, even if a user had multiple affiliations. Learn more [here](https://devcommunity.x.com/t/change-to-x-api-user-affiliation-data/237164).
</Update>

<Update label="Jan 16, 2025" description="X API">
  ### Launch of media upload endpoints

  Today, we launched new X API v2 [Media Upload endpoints](/x-api/media/introduction). Learn more [here](https://devcommunity.x.com/t/announcing-media-upload-endpoints-in-the-x-api-v2/234175/3).
</Update>

<Update label="Jan 13, 2025" description="Documentation">
  ### Launch of new documentation site

  Today, we launched our new X Developer Platform documentation site, [https://docs.x.com](https://docs.x.com).
</Update>

<Update label="Dec 17, 2024" description="X API">
  ### Launch of xurl tool

  Today, we launched [xurl](https://github.com/xdevplatform/xurl), a new tool that simplifies API testing for X developers, which now supports OAuth 2.0.
</Update>

<Update label="Nov 22, 2024" description="X API v2">
  ### Addition of community ID tweet field

  Today, we added the `community_id` Tweet Field to the X API v2. Learn more about it [here](https://x.com/tapshah21/status/1860061806653317126).
</Update>

<Update label="Sep 23, 2024" description="X API v2">
  ### Addition of DM blocking endpoints

  Today, we added the DM blocking and DM unblocking endpoints to the X API v2.
</Update>

<Update label="Aug 20, 2024" description="X API v2">
  ### Support for longform posts

  Today, we added the ability to create longform Posts with a length of 25k instead of 4k.
</Update>

<Update label="Aug 9, 2024" description="X API v2">
  ### Support for long form posts

  Today, we added the ability to create long form Posts using the X API v2
</Update>

<Update label="Aug 2, 2024" description="X API v2">
  ### Retrieve user affiliation

  Today, we added the ability to retrieve a User's affiliation programmatically using the X API v2
</Update>

<Update label="Jul 26, 2024" description="X API v2">
  ### Get article metadata

  Today, we added the ability to get Article metadata using the X API v2
</Update>

<Update label="Jun 17, 2024" description="X API v2">
  ### Get profile image and cover picture

  Today, we added the ability to get profile Image and cover picture URL via the X V2 API
</Update>

<Update label="Jan 16, 2024" description="X API v2">
  ### Addition of connection status field

  Today, we added the connection\_status field in the X API v2. Learn more about it [here](https://devcommunity.x.com/t/announcing-connection-status-field-in-the-user-object-in-the-x-api-v2/212588).
</Update>

<Update label="Dec 12, 2023" description="X API v2">
  ### Addition of trends lookup endpoint

  Today, we added the Trends lookup endpoint in the X API v2. Learn more about it [here](https://devcommunity.x.com/t/announcing-the-users-search-and-trends-lookup-endpoints-in-the-x-api-v2/210567).
</Update>

<Update label="Dec 8, 2023" description="X API v2">
  ### Addition of users search endpoint

  Today, we added the Users Search endpoint in the X API v2. Learn more about it [here](https://devcommunity.x.com/t/announcing-the-users-search-and-trends-lookup-endpoints-in-the-x-api-v2/210567).
</Update>

<Update label="Nov 29, 2023" description="X API v2">
  ### Get DM permissions

  Today, we added the ability to the get DM permissions via the X API v2. Learn more about it [here](https://devcommunity.x.com/t/dm-permissions-available-in-the-x-api-v2/209688).
</Update>

<Update label="Nov 20, 2023" description="X API v2">
  ### Launch of subscription type field

  Today, we launched a subscription\_type field on the User object in the X API v2. Learn more about it [here](https://devcommunity.x.com/t/new-subscription-type-field-is-available-in-the-twitter-api-v2/209219/2).
</Update>

<Update label="Nov 2, 2023" description="X API v2">
  ### Get posts usage endpoint

  Today, we launched an endpoint to programmatically get your posts usage in the X API v2. Learn more about it [here](https://developer.x.com/en/docs/twitter-api/usage/tweets/api-reference/get-usage-tweets).
</Update>

<Update label="Sep 28, 2023" description="X API v2">
  ### Launch of reposts lookup endpoint

  Today, we launched an endpoint to lookup reposts of a post in the X API v2. Learn more about it [here](https://developer.x.com/en/docs/twitter-api/tweets/retweets/api-reference/get-tweets-id-retweets).
</Update>

<Update label="Sep 28, 2023" description="X API v1.1">
  ### Deprecation of search endpoints

  Today, we are deprecating the search/tweets, users/search, and geo/search endpoints in the X API v1.1. Learn more [here](https://developer.x.com/en/docs/twitter-api/enterprise/powertrack-api/guides/powertrack_recovery_and_redundancy_features).
</Update>

<Update label="Sep 21, 2023" description="X API: Enterprise">
  ### Deprecation of Replay API endpoint

  Today, we are deprecating the Replay API endpoint from the enterprise X API. You can use the [recovery](https://developer.x.com/en/docs/twitter-api/enterprise/powertrack-api/guides/powertrack_recovery_and_redundancy_features) feature instead.
</Update>

<Update label="Aug 1, 2023" description="X API v1.1">
  ### Deprecation of historical Powertrack endpoints

  Today, we are deprecating the Historical Powertrack and Insights track endpoints from the enterprise X API.
</Update>

<Update label="Jun 26, 2023" description="X API v2">
  ### Removal of follows endpoints from Basic and Pro Tiers

  Today, we are removing the Follows and List Follows endpoints from the Basic and Pro tiers of the X API v2.
</Update>

<Update label="Jun 12, 2023" description="X API v2">
  ### Removal of manage blocks endpoint

  Today, we are removing the Manage Blocks endpoint from X API v2.
</Update>

<Update label="May 31, 2023" description="X API v2">
  ### Support for Bookmarks count and long posts

  Today, we added support for retrieving bookmarks count and the ability to retrieve posts with more than 280 characters in the X API v2.
</Update>

<Update label="Mar 14, 2023" description="X API v1.1">
  ### Deprecation of Statuses/Filter endpoint

  Today, we are deprecating the statuses/filter endpoint in the X API v1.1 Developers can use the filtered stream endpoint in the X API v2.
</Update>

<Update label="Jan 5, 2023" description="X API v2">
  ### Support for view counts

  Today, we are adding support for view counts in the X API v2. A new field called impression\_count is made available in the public\_metrics of the post payload.
</Update>

<Update label="Dec 21, 2022" description="X API v2">
  ### Addition of verified type field

  Today, we are adding a verified\_type user field to the X API v2 that indicates the type of verification a user account has (blue, business, government or none).
</Update>

<Update label="Dec 20, 2022" description="X API v2">
  ### Removal of source field

  Today, we are removing the source field from the post payload in the X APIs.
</Update>

<Update label="Oct 27, 2022" description="X API v2">
  ### Addition of Direct Messages endpoints

  Today, we are adding six v2 Direct Messages endpoints. This release includes three GET methods for retrieving Direct Message conversation events and three POST methods for creating new Direct Messages. These methods support group conversations for the first time.

  Please visit our [blog post](https://developer.x.com/en/blog/product-news/2022/new-v2-direct-messages-endpoints) to learn more about this update.
</Update>

<Update label="Sep 29, 2022" description="X API v2">
  ### Support for edited post metadata

  Today, we are adding the ability for developers to retrieve edited post metadata using the X API v2.

  Please visit our [blog post](https://developer.x.com/en/blog/product-news/2022/supporting-edit-tweet-functionality) to learn more about this update.
</Update>

<Update label="Aug 3, 2022" description="X API v2">
  ### Addition of filtering operator aliases

  Filtering/query operator "aliases" were added to search and filtered stream endpoints, across enterprise, premium, and v2. In many cases, the operator refers to posts instead of statuses, e.g. "in\_reply\_to\_tweet\_id" as an alias for "in\_reply\_to\_status\_id." In other cases, the new operator alias adds more clarity to the matching performed. For example., since posts can only have one video attachment, a new "has:video\_link" alias is provided for "has:videos." Check out the [v2 filtered stream operator table](https://developer.x.com/en/docs/twitter-api/tweets/filtered-stream/integrate/build-a-rule#list) to see more examples.
</Update>

<Update label="Jul 27, 2022" description="X API v2">
  ### Updates to reverse chronological home timeline

  Beginning today, the reverse chronological home timeline v2 endpoint can return every post created on a timeline over the last 7 days and the most recent 800 regardless of the creation date.
</Update>

<Update label="Jul 19, 2022" description="X API v2">
  ### New filtering operators for Filtered Stream

  Today, 10 new v2 filtering operators are now available to all developers building with the filtered stream endpoints, and another 10 are now more widely available.

  Please visit our [blog post](https://developer.x.com/en/blog/product-news/2022/twitter-api-v2-filtered-stream) to learn more about this update.
</Update>

<Update label="Jun 16, 2022" description="X API v2">
  ### Updates to streaming endpoints latency

  Today, we’re making updates to the streaming endpoints in the X API v2 to reduce the latency by 50%.
</Update>

<Update label="May 23, 2022" description="X API v2">
  ### Enabling v1.1 media endpoints in Essential Access

  Today, we're enabling the v1.1 media endpoints in Essential access of the X API v2.

  Please visit our [forum announcement](https://devcommunity.x.com/t/v1-1-media-endpoints-available-for-essential-access-in-the-twitter-api-v2/171664) to learn more about this update.
</Update>

<Update label="May 19, 2022" description="X API v2">
  ### Launch of Reverse Chronological Home Timeline endpoint

  Today, we’re launching a new endpoint that enables you to retrieve a collection of the most recent posts and reposts posted by who you follow.

  Please visit our [forum announcement](https://devcommunity.x.com/t/reverse-chronological-home-timeline-in-the-twitter-api-v2/171549) to learn more about this launch.

  Along with the new endpoints, the variants field is now available for the [media object](https://developer.x.com/en/docs/twitter-api/data-dictionary/object-model/media). This will give you the type of content attached with the URL.
</Update>

<Update label="Mar 24, 2022" description="X API v2">
  ### Launch of Bookmarks endpoints

  Today, we’re launching new endpoints that enable you to manage and lookup Bookmarks using the X API v2. The Bookmarks feature has long been available in the X app, but until now, there hasn’t been an endpoint that allows you to retrieve, create or build solutions to manage your Bookmarks via the API.

  Please visit our [forum announcement](https://devcommunity.x.com/t/build-with-bookmarks-on-the-twitter-api-v2/168804) to learn more about this launch.
</Update>

<Update label="Mar 17, 2022" description="X API v2">
  ### Launch of quotes lookup endpoint

  Today, we’re launching the [quotes lookup endpoint](https://developer.x.com/en/docs/twitter-api/tweets/retweets/introduction) that lets you get the quotes for a post ID.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/introducing-the-quote-tweets-lookup-endpoint-to-the-twitter-api-v2/168370) to learn more about this launch.
</Update>

<Update label="Feb 3, 2022" description="Documentation">
  ### Updates to documentation navigation

  We’ve heard your feedback. Finding content in our documentation could be difficult, and it was confusing when you clicked on a link and were taken to an entirely different side navigation.

  Today, we’ve released an updated docs navigation that enables you to browse the full offering of the X Developer Platform from a single side navigation. With this launch, we eliminated redundant pages, removed confusing icons, and improved how you can interact with the different elements within the navigation.

  If you have any feedback, please let us know via our [feedback channel](https://twitterdevfeedback.uservoice.com/forums/930250-twitter-api).
</Update>

<Update label="Jan 20, 2022" description="X API v2">
  ### Improvements to reposts and likes lookup endpoints

  Today, we’re launching improvements to the [reposts lookup](https://developer.x.com/en/docs/twitter-api/tweets/retweets/introduction) and the [Likes lookup](https://developer.x.com/en/docs/twitter-api/tweets/likes/introduction) endpoints, allowing you to get back the complete list of accounts who have Liked or reposted a post, not just the last 100 accounts to do so.

  To learn more about this launch, please visit our forum announcement to learn more about this launch.
</Update>

<Update label="Dec 14, 2021" description="X API v2: Authentication">
  ### Support for OAuth 2.0 authentication

  Today, all developers can now authenticate using OAuth 2.0 by selecting OAuth 2.0 as an authentication method in the Developer Console. We’ve added support for confidential and public clients and all relevant v2 endpoints to use this authentication method as part of this release.

  OAuth 2.0 is an industry-standard authorization protocol that provides developers more control over an application’s scopes and improves authorization flows across multiple devices. In other words, developers building applications for people on X will have more control over the information their App requests from its users, so that you only have to ask your end-users for the data and information you need.

  This modern authorization protocol will allow you to present your end-users with a more streamlined consent flow for authorizing your app, which only displays the specific scopes you have requested from them.

  To learn more about this launch, please visit our forum announcement.
</Update>

<Update label="Nov 15, 2021" description="X API v2: Early Access">
  ### Major platform updates to X API v2

  **Major platform updates: X API v2 is now the primary version, new Essential and Elevated access, and Policy changes**

  Today, we are announcing that X API v2 is now the primary version of the X API. We have launched enough endpoints and functionality into X API v2 to satisfy the needs of 90% of all existing Apps built on the X API.

  We are launching the following changes today to further improve upon the X API v2 developer experience:

  * Fast and free Essential access to the API, and free Elevated access to developers who have had their use cases approved. We have a lot more details on these access levels available on our About the X API page.

  * We are removing language in our Developer Policy that restricted how you build with X’s core features, and limited the number of users you can support through your app.

    * We are opening up our platform to encourage you to build tools and products that make X better, healthier, and extend the public conversation. [See a list of solutions we’d love to see you build](https://developer.x.com/en/docs/twitter-api/what-to-build).

    * Specifically, we’ve removed terms that restricted replication of the X experience, including X’s core features as well as terms that required permission to have high numbers of user tokens.

    * We know that building solutions that help people on X often means a developer has to build (or replicate) some of the things that are available on X. These changes to our Developer Policy are intended to drive clarity for the developer ecosystem and provide an open API platform that makes it easier for developers to build, innovate, and make an impact on the public conversation.

  We go into a lot more detail on this launch and the X API launches that led to this moment in our [forum post](https://devcommunity.x.com/t/ushering-in-a-new-era-for-the-twitter-developer-platform-with-the-twitter-api-v2/162087).

  In addition to exploring earlier changelog entries, we’ve put together some key resources that you can review to understand what all has released to X API v2 to-date:

  * [X API endpoint map](/x-api/migrate/x-api-endpoint-map)

  * [About the X API](/x-api/getting-started/about-x-api)
</Update>

<Update label="Nov 15, 2021" description="X API v2: Early Access">
  ### Launch of list lookup endpoints

  Today, we’re launching the new List lookup endpoints to X API v2. These endpoints will allow users to retrieve details on specified Lists such as followers, members, posts and more. The data retrieved can be used to build solutions that solve for curation, analysis and discoverability use cases and needs. In addition to new List endpoints, a new list: operator has been made available at the Academic Research access level. This will be available to use on search posts and post counts.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/announcing-list-lookup-endpoints-for-the-twitter-api-v2/161965).
</Update>

<Update label="Nov 15, 2021" description="X API v2: Early Access">
  ### Additions to Spaces endpoints

  We are adding functionality to the Spaces endpoint to return the list of people who purchased a ticket to a Space, as well as support for Topics.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/adding-new-functionality-to-spaces-endpoints/161959).
</Update>

<Update label="Nov 3, 2021" description="X API v2: Early Access">
  ### Launch of manage posts endpoints

  Today, we’re launching new manage posts endpoints to the X API v2. In addition to post and post delete functionality, we’ve added the ability to post polls, tag people in images, create posts with reply settings, and post to Super Followers.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/announcing-manage-tweets-endpoints-for-the-twitter-api-v2/161501).
</Update>

<Update label="Oct 12, 2021" description="X for Websites">
  ### Changes to embedded buttons

  Today, we're making some changes to X's embedded buttons. Buttons are now more rounded to match X.com buttons and we've (very slightly) updated our color palette.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/embedded-buttons-have-a-new-look/160528).
</Update>

<Update label="Sep 29, 2021" description="X API v2: Early Access">
  ### Launch of lists endpoint group

  Today, we’re launching the new Lists endpoint group to X API v2. These endpoints will allow you to build solutions that curate and organize posts based on preferences, interests, groups, or topics.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/announcing-new-twitter-api-v2-manage-list-endpoints/159980).
</Update>

<Update label="Sep 22, 2021" description="X API v2: Early Access">
  ### Launch of mutes lookup endpoint

  Today, we’re launching the new [mutes lookup](https://developer.x.com/en/docs/twitter-api/users/mutes/introduction) endpoint to the X API v2. This endpoint will allow authenticated users to retrieve and get information on the accounts they have muted.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/announcing-new-mutes-lookup-endpoint-for-the-twitter-api-v2/159680).
</Update>

<Update label="Sep 9, 2021" description="OAuth 2.0 beta now available">
  ### Launch of OAuth 2.0 beta

  Today, we’re launching a beta of OAuth 2.0 and fine-grained scopes on the X API v2. Developers interested in shaping the future of OAuth 2.0 on the X Developer Platform, can request access to the OAuth 2.0 beta.

  OAuth 2.0 is the industry standard for authentication and will allow for a more modern authorization experience.

  The OAuth 2.0 beta lets you test this new functionality in a v2 Project and associated App and give us feedback before a General Availability release. However, since this implementation of OAuth 2.0 is currently in development, we strongly recommend that you refrain from testing on a public, production environment, or app.

  To learn more about this launch, please visit our forum announcement.
</Update>

<Update label="Aug 25, 2021" description="Batch compliance endpoints now available in X API v2">
  ### Launch of Batch Compliance endpoints

  Today, we’re launching the new [batch compliance endpoints](https://developer.x.com/en/docs/twitter-api/compliance/batch-compliance/introduction) to the X API v2 to make it easier for developers using the X API to keep their X data in compliance with our [Developer Agreement and Policy](https://developer.x.com/en/developer-terms/policy). These endpoints allow developers and researchers to batch upload large amounts of post or User IDs and understand what action is needed to ensure that their datasets reflect user intent and the current state of the content on X.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/new-batch-compliance-endpoints-available-on-the-twitter-api-v2/158534).
</Update>

<Update label="Aug 18, 2021" description="Spaces endpoints now available in X API v2">
  ### Launch of Spaces endpoints

  Today, we’re launching the new [Spaces endpoints](https://developer.x.com/en/docs/twitter-api/spaces/overview) and a [new top-level Spaces data dictionary](https://developer.x.com/en/docs/twitter-api/data-dictionary/object-model/space) to the X API v2. The Spaces endpoints enable you to lookup Spaces by Space ID or user ID, or using keywords, hashtags, or usernames of people mentioned in a title. The new data dictionary contains relevant information about a Space such as its title, ticketed status, and participant metrics; all user IDs can be expanded into full objects.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/introducing-new-spaces-endpoints-on-the-twitter-api-v2/158213).
</Update>

<Update label="Aug 16, 2021" description="New data object to help clarify video view limitation for Engagement API">
  ### New object for video views limitation

  Previously, when you requested video view metrics using the enterprise [Engagement API](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api) on posts that are older than 1800 days old, we delivered a zero value without much context. Today, we will start delivering a new object in these cases called unsupported\_for\_video\_views\_tweet\_ids, which will include a comma-separated list of post IDs that are older than 1800 days old. You will still receive all other requested metrics for these posts in a separate object.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/new-engagement-api-video-views-object-to-clarify-limitation/158163).
</Update>

<Update label="Aug 11, 2021" description="Media alt text field now available in X API v2">
  ### Addition of alt text field

  Today, we are making the alt\_text field available in the X API v2 media object, in order to enable developers to build more consciously for accessibility.

  To request this field, you must pass the expansions=attachments.media\_keys parameter, as well as the media.fields=alt\_text parameter. If included in your request, this field will return the alt text for any posts that include images with alt text.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/media-alt-text-field-now-available-in-twitter-api-v2/157939).
</Update>

<Update label="Jul 14, 2021" description="reposts now available in X API v2">
  ### Launch of reposts endpoints

  Today, we’re launching new [reposts](https://developer.x.com/en/docs/twitter-api/tweets/retweets) endpoints to X API v2.  Developers can now use these endpoints to repost or undo a repost on behalf of an authenticated user, or to look up who reposted a given post.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/announcing-new-twitter-api-v2-retweets-endpoints/156827).
</Update>

<Update label="Jun 30, 2021" description="Manage mutes now available in X API v2">
  ### Launch of manage mutes endpoints

  Today, we’re launching new [manage mutes](https://developer.x.com/en/docs/twitter-api/users/mutes/introduction) endpoints to the X API v2. These endpoints will allow authenticated users to mute or unmute accounts.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/announcing-new-manage-mutes-endpoints-for-the-twitter-api-v2/156261).

  We have now reduced the `max_results` that can deliver with the [full-archive search](/x-api/posts/full-archive-search) endpoint when you are requesting the `context_annotations` field with the `tweet.fields` parameter to 100, meaning that you can only pull up to 100 posts with the field per page.
</Update>

<Update label="Jun 29, 2021" description="Redundant connections and backfill are now available with v2 filtered stream and sampled stream">
  ### Reliability features for streaming endpoints

  Today, we are launching two reliability streaming features for X API v2’s filtered stream and sampled stream called backfill and redundant connections, which are now available on the Academic Research product track.

  The redundant connections feature enables you to connect to a given stream two times, which can help to ensure that you maximize streaming up-time in case one of your streams experiences a disconnection.

  Backfill can be utilized by adding the backfill\_minutes parameter and a whole number between one and five to your streaming request, and allows you to request missed data that might have resulted from a disconnected stream.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/new-reliability-and-recovery-functionality-available-for-twitter-api-v2-streaming-endpoints/156244/2).
</Update>

<Update label="Jun 24, 2021" description="post counts now available in X API v2">
  ### Launch of post counts endpoints

  Today, we’re launching the new [post counts endpoints](/x-api/posts/counts/introduction) to the X API v2. This includes two different endpoints: Recent post counts, which is available to all product tracks, and full-archive post counts, which is currently only available to the Academic Research Product Track. You can use these endpoints to receive the count of posts that matches a specified query.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/introducing-new-tweet-counts-endpoints-to-the-twitter-api-v2/155997).
</Update>

<Update label="Jun 21, 2021" description="Improvements to Teams Functionality">
  ### Improvements to teams

  Today, we’re launching key improvements to the functionality of teams based on feedback we’ve heard from the community. We have updated the style and design of the team page. We also made changes to the invitation flow to make it easier to invite team members or to learn more about why an invitation might have failed. If you have a team account you can check out the changes by viewing the [teams page](https://developer.x.com/en/portal/teams) of the Developer Console. To learn more about teams check out our [documentation on the subject](https://developer.x.com/en/docs/Developer%20Console/overview#team) and related [FAQ](https://developer.x.com/en/docs/Developer%20Console/faq#dev-portal-management-faq).

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/announcing-improvements-to-the-functionality-of-teams/155447/2).
</Update>

<Update label="Jun 18, 2021" description="Retiring the standard v1.1 GET /help/configuration endpoint">
  ### Retirement of configuration endpoint

  Today, we retired the standard v1.1 GET /help/configuration endpoint.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/retiring-the-1-1-configuration-endpoint/153319).
</Update>

<Update label="May 26, 2021" description="Consolidating the oEmbed endpoint">
  ### Consolidation of oembed endpoint

  Today, we’re sharing that the v1.1 oEmbed endpoint will be retired and removed on November 23, 2021, so that new features can be supported in a consistent manner. After that date, the only official and supported API endpoint for X oEmbeds (embedded posts and timelines) will be via publish.x.com/oembed.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/consolidating-the-oembed-functionality/154690/2).
</Update>

<Update label="May 20, 2021" description="Blocks and Likes lookup available in X API v2">
  ### Launch of blocks and likes lookup endpoints

  Today, we’re launching the new [blocks](/x-api/users/blocks) and [Likes](/x-api/posts/likes) lookup endpoints to the X API v2. These endpoints enable you to use the v2 API to get information about which posts an account has liked, what users have liked a post, and who you or an authenticated user has blocked.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/announcing-twitter-api-v2-likes-lookup-and-blocks-lookup/154353).
</Update>

<Update label="Apr 22, 2021" description="Manage Likes available in X API v2">
  ### Launch of manage likes endpoints

  Today, we’re launching the new [manage Likes](https://developer.x.com/en/docs/twitter-api/tweets/likes) endpoints to the X API v2. These endpoints enable you to use the v2 API to like and unlike posts.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/announcing-new-manage-likes-endpoints-for-thetwitter-api-v2/152780).
</Update>

<Update label="Apr 7, 2021" description="Manage blocks available in X API v2">
  ### Launch of manage blocks endpoints

  Today, we’re launching the new [manage blocks](/x-api/users/blocks) endpoints to the X API v2. These endpoints enable you to block or unblock accounts on behalf of a user using user IDs.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/announcing-manage-blocks-for-twitter-api-v2/152358/2).
</Update>

<Update label="Mar 3, 2021" description="Removing support for Embedded Like, Collection, and Moment Timelines">
  ### Removal of support for embedded timelines

  Today we’re sharing our plans for the future of [embedded timeline widgets](https://developer.x.com/en/docs/x-for-websites/timelines/overview). On June 23rd 2021, we plan to retire the Likes, Collections, and Moments timelines. We recommended you use the [Profile](https://developer.x.com/en/docs/x-for-websites/timelines/guides/profile-timeline) and [Lists](https://developer.x.com/en/docs/x-for-websites/timelines/guides/list-timeline) timelines, which we’re updating to become faster, easier to use, and more up-to-date with X features and functionality.

  You can learn more about this change in our [forum announcement](https://devcommunity.x.com/t/removing-support-for-embedded-like-collection-and-moment-timelines/150313).
</Update>

<Update label="Feb 10, 2021" description="Manage follows available in X API v2">
  ### Launch of manage follows endpoints

  Today, we’re launching the new [manage follows](/x-api/users/follows) endpoints to the X API v2. These endpoints enable you to follow or unfollow accounts on behalf of a user using their user ID. This launch comes just a few months after the launch of the [follows lookup](/x-api/users/follows) endpoints, which allow you to retrieve an account’s followers and who they are following.

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/introducing-the-new-manage-follows-endpoints-to-the-twitter-api-v2/149465).
</Update>

<Update label="Jan 26, 2021" description="Introducing the X API v2 Academic Research product track">
  ### Introduction of Academic Research product track

  Today, we are introducing the new [Academic Research product track](/resources/fundamentals/developer-apps) to [X API v2](/x-api/introduction). This update introduces a new application process for Academic Researchers that will provide those that are approved with an Academic Research [Project](/resources/fundamentals/developer-apps) that will unlock greater access and advanced functionality.

  With the new Academic Research product track, you will be able to access the following:

  * The new X API v2 [full-archive search endpoint](/x-api/posts/full-archive-search), which is only available to the Academic Research product track at this time.

  * An increased [post cap](/x-api/fundamentals/post-cap) of 10 million, up from the 500,000 that is available to the [Standard product track](/resources/fundamentals/developer-apps) at the Basic [access level](https://developer.x.com/en/products/x-api/early-access/guide#na_2).

  * New filter operators available to [recent search](/x-api/posts/recent-search), [full-archive search](/x-api/posts/full-archive-search), and [filtered stream](/x-api/posts/filtered-stream), including `$` (aka cashtag), `bio` (only available via filtered stream), `bio_name` (only available via filtered stream), `bio_location` (only available via filtered stream), `place`, `place_country`, `point_radius`, `bounding_box`, `-is:nullcast`, `has:cashtags` and `has:geo`.

  * An increased rule limit for filtered stream of 1,000 concurrent rules, up from the 25 that is available to the Standard product track at the Basic access level.

  * An increased query and rule character limit of 1,024 characters long, up from the 512 character limit that is available to the Standard product track at the Basic access level

  To learn more about this launch, please visit our [forum announcement](https://devcommunity.x.com/t/introducing-the-new-academic-research-product-track/148632).
</Update>

<Update label="Dec 18, 2020" description="Conversation reply settings post field for v2 X API">
  ### Addition of reply settings field

  Today we are launching a new field in the post object called reply\_settings. This field is available on all X API v2 endpoints that return posts including post lookup, hide replies, recent search, sampled stream, filtered stream, follows lookup, user post timeline, and user mention timeline endpoints or by [expanding](/x-api/fundamentals/expansions) the post object in any endpoint.

  This field indicates how the post author has allowed others to reply to their posts, whether it’s everyone, just the people they mention in the post, or those they follow. The field values returned by the `reply_settings` field include `everyone`, `mentionedUsers`, and `following`. If no conversation controls are set for the post, this will still show up in the post object with `everyone` value for the field.
</Update>

<Update label="Dec 17, 2020" description="User post timeline and user mention timeline available in X API v2">
  ### Launch of user post and mention timeline endpoints

  Today, we’re launching the new [user post timeline and user mention timeline endpoints](/x-api/posts/timelines) to the X API v2. These endpoints enable you to request the posts composed by, or mentioning, a specified account on X. Learn more in the forum post announcement.
</Update>

<Update label="Dec 17, 2020" description="Follows lookup available in the X API v2">
  ### Launch of follows lookup endpoints

  Today, we’re launching the new [follows lookup endpoints](/x-api/users/follows) to the X API v2. These endpoints enable you to retrieve an account’s followers and who they are following using their user ID. Learn more in the forum post announcement.
</Update>

<Update label="Nov 16, 2020" description="Retiring some Labs v2 endpoints">
  ### Retirement of Labs v2 endpoints

  Retired Labs v2 recent search and hide replies endpoints

  We have retired the following endpoints. If you were using the Labs versions of these endpoints, you can use the linked migration guides to update your integration to start using the new X API v2 versions:

  * [Recent search v2](/x-api/posts/search/migrate/overview)

  * [Hide replies v2](/x-api/posts/hide-replies/migrate)

  We also have additional details about migration to the new X API v2 via our [migration hub](/x-api/migrate/overview).

  If you have any questions, please reach out to our [Labs forum category](https://devcommunity.x.com/c/labs/57).
</Update>

<Update label="Oct 12, 2020" description="Retiring some Labs v1 endpoints">
  ### Retirement of Labs v1 endpoints

  On August 12th, 2020, we launched the new X API v2: Early access. With this release, we graduated several endpoints to X API v2 from the Labs program, and announced that the Labs version of the endpoints would remain in a deprecated state for 60 days before retiring them.

  Today marks 60 days since the launch, meaning that we have retired the following endpoints. If you are using the Labs versions of these endpoints, you can use the linked migration guides to update your integration to start using the new X API v2 versions:

  * post metrics v1

  * Filtered stream v1

  * Sampled stream v1

  We also have additional details about migration to the new X API v2 via our [migration hub](/x-api/migrate/overview).

  If you have any questions, please reach out to our [Labs forum category](https://devcommunity.x.com/c/labs/57).
</Update>

<Update label="Sep 3, 2020" description="post consumption status bar added to the new Developer Console experience">
  ### Addition of post consumption status bar

  In the [main dashboard page](https://developer.x.com/en/portal/dashboard) of the new Developer Console, you can now check your usage towards the [post cap](/x-api/fundamentals/post-cap) of 500,000 posts per month. This cap is applied at the Project level, across the following v2 endpoints in Basic access: filtered stream, and recent search.

  In order to see this feature and use the new v2 endpoints, you will need to activate the [new Developer Console experience](https://developer.x.com/en/portal/opt-in.html).
</Update>

<Update label="Aug 19, 2020" description="Hide replies available in v2 X API">
  ### Launch of Hide Replies endpoint

  Today, we’re launching the new hide replies endpoint into the v2 X API. This endpoint enables you to hide abusive, distracting, or misleading replies to posts – a crucial piece to improving the health of the public conversation. Learn more in the forum post announcement.

  The same endpoint in X Developer Labs is now deprecated, and it will be retired in 90 days. Learn how to [migrate to the v2 endpoint.](/x-api/posts/hide-replies#comparing-twitter-apis-hide-replies-endpoints)
</Update>

<Update label="Aug 12, 2020" description="X API v2: Early Access released">
  ### Early access to X API v2 endpoints

  Today we announced [Early Access to the first endpoints of the new X API](https://blog.x.com/developer/en_us/topics/tools/2020/introducing_new_twitter_api.html)!

  The new X API features a new API foundation which will allow us to deliver new functionality faster; an updated data format and new functionality that gives you more control over which fields you receive; new post, user, and media fields; and a set of updated endpoints that enable you to listen to and analyze posts, including the following:

  * [post lookup](/x-api/posts/post-lookup-by-post-ids)

  * [User lookup](/x-api/users/user-lookup-by-id)

  * [Recent search](/x-api/posts/recent-search)

  * [Filtered stream](/x-api/posts/filtered-stream)

  * [Sampled stream](/x-api/stream/stream-sampled-posts)

  You can find a full list of the new functionality available, and find migration resources on our [X API v2: Early Access docs page](https://developer.x.com/en/docs/x-api/early-access).

  Learn more about what we have planned in our “[Guide to the future of the X API](https://developer.x.com/en/docs/x-api/early-access)”.
</Update>

<Update label="Aug 12, 2020" description="Deprecating certain Labs endpoints">
  ### Deprecation of Labs endpoints

  We are deprecating certain Labs endpoints due to the launch of their X API v2 replacements in this release.

  The following Labs v1 endpoints will be retired 60 days from today's release:

  * post metrics v1

  * Filtered stream v1

  * Sampled stream v1

  The following Labs v2 endpoint will be retired 90 days from today’s release:

  * Recent search v2
</Update>

<Update label="Jul 13, 2020" description="Improvements to Hide replies">
  ### Improvements to hide replies

  We added the ability to unhide a reply. Additionally, previously unhidden replies can now be hidden again via this endpoint.

  Get more details in the [Hide replies documentation](https://developer.x.com/en/docs/labs).
</Update>

<Update label="Jul 8, 2020" description="Retiring certain Labs v1 endpoints">
  ### Retirement of Labs v1 endpoints

  Today we are retiring the Labs v1 posts and users, hide replies, and recent search endpoints.

  You can read more about our Labs v1 plan in our [forum announcement](https://devcommunity.x.com/t/update-on-labs-v1-endpoints/138641).
</Update>

<Update label="Jul 7, 2020" description="quotes available for the /totals endpoint">
  ### Addition of quote tweets metric

  Today, the `quote_tweets` 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 quote count for all posts by using app-only authentication.

  You can read more about this change in our [forum post](https://devcommunity.x.com/t/how-the-new-retweets-and-comments-metric-is-returned-with-the-twitter-api/139131).
</Update>

<Update label="Jul 1, 2020" description="Adding two new posts metrics">
  ### Addition of new post metrics

  Today we are adding two new non-public metrics subfields, `user_profile_clicks` and `url_link_clicks`, to the post object in the X Developer Labs post lookup endpoints. They will be returned when using the `tweet.fields` parameter with any of the following values: `non_public_metrics`, `organic_metrics`, or `promoted_metrics`.

  To learn more, please visit the [post lookup API reference](https://developer.x.com/en/docs/labs/tweets-and-users/api-reference/get-tweets-id)
</Update>

<Update label="Jun 15, 2020" description="Changes to X web, iOS and Android repost counts">
  ### Changes to repost counts

  Starting today, X web, iOS and Android will be showing the total 'reposts and comments' count per post. Using the X API, the total 'reposts and comments' number matching the X interface can be calculated by adding the `retweet_count` and `quote_count` when available. Additionally `quote_count` will be the total unique accounts that have quoted the post, rather than the total posts quoting the post. For more details, please see our [forum post](https://devcommunity.x.com/t/how-the-new-retweets-and-comments-metric-is-returned-with-the-twitter-api/139131/2).
</Update>

<Update label="May 28, 2020" description="Defining organic and promoted metrics groupings for post and media objects">
  ### Organic and promoted metrics groupings

  We are adding `organic_metrics` and `promoted_metrics` to the post and media objects in the post lookup endpoints.
</Update>

<Update label="May 6, 2020" description="Metrics in posts and recent search endpoints">
  ### Addition of metrics to endpoints

  We are adding metrics to the post and media objects in the post lookup and recent search endpoints.

  You can read more about these changes in our [forum announcement](https://devcommunity.x.com/t/adding-metrics-to-the-tweets-and-recent-search-endpoints-in-labs/135315)
</Update>

<Update label="Apr 29, 2020" description="COVID-19 Stream and Compliance endpoints">
  ### Launch of COVID-19 endpoints

  Today we are launching a new COVID-19 stream endpoint and an accompanying compliance endpoint.

  You can read more about these changes in our [forum announcement.](https://devcommunity.x.com/t/new-covid-19-stream-endpoint-available-in-twitter-developer-labs/135540)
</Update>

<Update label="Mar 31, 2020" description="PowerTrack's Replay API now delivers current user profile data">
  ### Updates to Replay API user profiles

  Starting today, the Replay API will deliver user profile objects that reflect the referenced user at the time the Replay API is running. This change to deliver current user profile objects is similar to the recent Historical PowerTrack update below from Nov. 25, 2019.
</Update>

<Update label="Mar 23, 2020" description="post annotations in posts and recent search endpoints">
  ### Addition of post annotations

  We are adding annotations to the post object in the posts and recent search endpoints.

  You can read more about this change in our [forum announcement](https://devcommunity.x.com/t/adding-annotations-to-tweets-and-recent-search-endpoints-in-labs/135193).
</Update>

<Update label="Mar 10, 2020" description="Major updates to the X Developer Policy">
  ### Updates to developer policy

  Today, we announced a significant [update to the Developer Policy](https://developer.x.com/en/developer-terms/policy). We encourage you to read more about this via our [forum](https://devcommunity.x.com/t/a-new-easier-to-understand-twitter-developer-policy/135038) and [blog](https://blog.x.com/developer/en_us/topics/community/2020/twitter_developer_policy_update.html) posts, and to review the revised policy. The Developer Policy is one of the foundations for your use of the X API and it is important to understand your commitments.
</Update>

<Update label="Feb 26, 2020" description="Introducting the hide replies endpoint">
  ### Launch of Hide Replies endpoint

  We want to help people feel safe and comfortable having conversations on X. As part of that, today we’re excited to give post authors more control over the conversations they start by supporting the hide replies feature with a new [endpoint](/x-api/posts/hide-replies).

  You can read more about this new endpoint in our [forum announcement](https://devcommunity.x.com/t/introducing-the-hide-replies-endpoint/134683).
</Update>

<Update label="Feb 25, 2020" description="v2 of Labs endpoints: posts and Users, Recent Search, Hide Replies">
  ### Release of v2 Labs endpoints

  Today, we are bringing our posts and Users, Recent Search and Hide Replies endpoints to v2 of Labs. We are deprecating Labs v1 endpoints and will fully retire them 90 days after this initial release. We will also keep our v1 documentation available for this duration. You can provide us feedback on this versioning strategy via our [feedback channel](https://twitterdevfeedback.uservoice.com/).

  We're releasing the following changes to posts and Users:

  * Introduce [fields](/x-api/fundamentals/fields) as a query parameter

  * Remove [formats](https://developer.x.com/en/docs/labs#payload) as a query parameter

  * Add path variable for single ID [lookup](https://developer.x.com/en/docs/labs/overview/versioning/migration-guide#id-lookup-path) in posts and Users

  * Adjusting the path and query parameters for single and multi-username [lookup](/x-api/migrate/overview#username-lookup-path) in GET /users

  * Change field name `stats` to `public_metrics`

  Other changes include:

  * Remove the `most_recent_tweet_id` expansion in Users

  * Remove HTML tags from the `source` field in posts to make that field easier to parse

  The core search, pagination and other functionality of Recent Search will stay the same.

  We have put together some [migration materials](/x-api/migrate/overview) for when you update from v1 to v2.

  You can read more about this change in our [forum announcement](https://devcommunity.x.com/t/releasing-a-new-version-of-labs-endpoints/134219).
</Update>

<Update label="Feb 7, 2020" description="X API: Enterprise">
  ### Addition of drop/undrop events to Compliance Firehose

  Today we added new drop/undrop event types to the Compliance Firehose API. You can read more about them in our [documentation.](/x-api/enterprise-gnip-2.0/fundamentals/firehouse)
</Update>

<Update label="Jan 21, 2020" description="X API: Standard v1.1">
  ### Changes to access token management

  Today, we're making changes to the way that Access Tokens and Access Token Secrets are presented and managed within the [applications Dashboard on developer.x.com](https://developer.x.com/content/developer-twitter/en/apps).

  In order to make API integrations more secure, we will no longer show the Access Token and Access Token Secret on the Dashboard beyond the first time that these values are generated.

  After the first time, these credentials can not be retrieved. You will be able to regenerate the tokens on the Dashboard, but this will invalidate your current token and secret.

  You can read more about this change in our [forum announcement](https://devcommunity.x.com/t/upcoming-changes-to-access-token-and-secret-management/130851).
</Update>

<Update label="Jan 15, 2020" description="X API: Standard v1.1">
  ### Removal of SPDY support

  Starting January 15, 2020, all connections to the X API (and all other X domains) will no longer support SPDY connections.

  You can read more about this change in our [forum announcement](https://devcommunity.x.com/t/removing-support-for-spdy-protocol-on-twitter/132530).
</Update>

<Update label="Jan 6, 2020" description="New Recent search endpoint available in Labs">
  ### Launch of recent search endpoint in Labs

  Today, we are releasing a new endpoint to [search for posts posted in the last 7 days](/x-api/posts/recent-search).

  Learn more about this launch via our [forum announcement.](https://devcommunity.x.com/t/new-recent-search-endpoint-available-in-labs/133076)
</Update>

<Update label="Dec 29, 2019" description="X API: Standard v1.1">
  ### Update to Twurl CLI

  A new updated major release of our X API CLI, `[twurl](https://github.com/twitter/twurl)`, is now available. This release includes a number of bug fixes and enhancements and introduces Bearer Token support which helps to add functionality around the Premium and X Developer Labs endpoints. Read more in our [forum post](https://devcommunity.x.com/t/twurl-0-9-5-released/132966).
</Update>

<Update label="Dec 10, 2019" description="post annotations added to the post Object for sampled stream and filtered stream endpoints in Labs">
  ### Addition of post annotations in streams

  Today in X Developer Labs, we are releasing new metadata elements to the default post payload. These new fields, rendered as part of the post payload, will provide more contextual information about the post.

  Learn more about this launch via our [forum announcement](https://devcommunity.x.com/t/tweet-annotations-added-to-the-tweet-object-for-the-sampled-stream-and-filtered-stream-endpoints-in-labs/132407).
</Update>

<Update label="Nov 25, 2019" description="X API: Enterprise v1.1">
  ### Updates to Historical PowerTrack user profiles

  Today, we’re updating our "batch historical posts" endpoint (Historical PowerTrack) to provide user profile location, bio description, and display name information that reflects values in place at the time of the job processing. When the updated user objects are delivered, there will be a new "updated" string array in the User/Actor object.

  There are up to three possible values: name, description, location:

  `"updated": ["name", "description", "location"]`

  See the [documentation on Historical PowerTrack's data format](https://aem-author-production-version-6-3.twitter.biz/content/developer-twitter/en/docs/tweets/batch-historical/guides/powertrack-data-format.html) for more details.
</Update>

<Update label="Oct 29, 2019" description="X API: Premium v1.1">
  ### Addition to Account Activity API

  Today, we’re releasing a new feature to the Account Activity API that will provide developers with the ability to view whether an account that mentions your subscribed user is blocked.

  You can read more about the `user_has_blocked` [data object structure](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-data-object-structure) and check out our [forum announcement](https://devcommunity.x.com/t/new-release-account-activity-api-user-has-blocked-field/131157) for more details.
</Update>

<Update label="Oct 22, 2019" description="New sampled stream endpoint available in Labs">
  ### Launch of sampled stream endpoint in Labs

  Today, we are releasing a new endpoint to [stream a sample of all public posts](/x-api/posts/recent-search) in real-time, as they are posted.

  Learn more about this launch via our [forum announcement.](https://devcommunity.x.com/t/new-sampled-stream-endpoint-available-in-labs/130958)
</Update>

<Update label="Sep 18, 2019" description="New filtered stream endpoint available in Labs">
  ### Launch of Filtered Stream endpoint in Labs

  Today, we are releasing a [new streaming endpoint](/x-api/posts/filtered-stream) to retrieve posts, and an endpoint to manage your filters in X Developer Labs. With these endpoints, you will be able to retrieve up to 500,000 posts per month (maximum 50 posts per second); you can set up to 10 filter rules on your stream (these can be applied at the same time).

  Learn more about this launch via our [forum announcement](https://devcommunity.x.com/t/new-filtered-stream-endpoints-available-in-labs-and-the-future-of-statuses-filter/129888).

  Requests parameters documented in the API reference pages are now clearly marked as either optional or required. Additionally, API reference pages will describe a JSON body payload when this is allowed by a request.
</Update>

<Update label="Aug 27, 2019" description="New post metrics are now available in Labs">
  ### Launch of post metrics in Labs

  You can now retrieve engagement data for any post or list of posts from owned/authorized accounts. The posts you query must be no older than 30 days and cannot be reposts.

  [GET /tweets/metrics/private](https://developer.x.com/en/docs/labs/tweet-metrics/overview.html) supports the following metrics:

  * `impressions`

  * `reposts`

  * `quotes`

  * `likes`

  * `replies`

  * `video views`

  * `video view quartiles` (where the requester is also the author of the media)

  Learn more about this launch via our [forum announcement](https://devcommunity.x.com/t/new-twitter-developer-labs-release-metrics-endpoint/129122).
</Update>

<Update label="Aug 15, 2019" description="X API: Standard v1.1">
  ### Changes to DM permissions

  Starting today, applications that need to create Direct Messages will be required to have "Read, Write, and Direct Messages" app permissions (RW+DM). Applications attempting to create Direct Messages with only the RW app permission will receive the following error:

  `{"code": 93,"message": "This application is not allowed to access or delete your direct messages."}`

  You can learn more about this change via our [forum announcement](https://devcommunity.x.com/t/updates-to-app-permissions-direct-message-write-permission-change/128221).
</Update>

<Update label="Aug 12, 2019" description="New expansion for GET /users: pinned post in X Developer Labs">
  ### Addition of pinned post expansion

  `pinned_tweet_id` will expand a user’s pinned post through our user object expansion.
</Update>

<Update label="Jul 31, 2019" description="New metadata available for quote counts">
  ### Addition of quote counts metadata

  Developers can use the new Labs endpoints to pull counts of quotes.
</Update>

<Update label="Jul 31, 2019" description="New expansion for GET /users: most recent post">
  ### Addition of most recent post expansion

  `most_recent_tweet_id` will expand a user’s most recent post through our user object expansion.

  Learn more about this launch via our [forum announcement](https://devcommunity.x.com/t/update-to-twitter-developer-labs/128060).
</Update>

<Update label="Jul 25, 2019" description="X API: Standard v1.1">
  ### Requirement for TLS 1.2

  Today, all connections to the X API (and all other X domains) will require TLS 1.2.

  You can read more about this change in our [forum announcement](https://devcommunity.x.com/t/removing-support-for-legacy-tls-versions-1-0-1-1-on-twitter/126648/2).
</Update>

<Update label="Jul 15, 2019" description="X API: Premium v1.1">
  ### New Account Activity API endpoint

  Starting today, we are introducing the new [Account Activity API endpoint](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#api-reference) to deactivate user subscriptions using application-only OAuth.

  This new endpoint offers developers the convenience of only having to provide a bearer token to deactivate a subscription, without requiring the subscribed user’s access token.

  We are immediately marking the existing enterprise Account Activity API endpoint used to deactivate user subscriptions with 3-Legged OAuth as deprecated. The endpoint will be retired and no longer be available starting from January 15, 2020.

  Developers can learn more about this API in our [documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#api-reference).
</Update>

<Update label="Jun 20, 2019" description="New expansions for GET /tweets: referenced author and mentioned user">
  ### New expansions for tweets endpoint

  We added two new expansions to the [GET /tweets](https://developer.x.com/en/docs/labs/tweets-and-users/api-reference/get-tweets.html) endpoint:

  entities.mentions.username will expand the username of any recognized user mention in a post into a full user object.

  `referenced_tweets.id.author_id` expands the ID of the author of any referenced post, when one of the posts requested is a repost, Quoted post or Reply. This expansion will also expand the referenced post ID into a full object.
</Update>

<Update label="Jun 11, 2019" description="GET /tweets and GET /users are now supported in Labs">
  ### Support for tweets and users endpoints in Labs

  The first two endpoints are now available via the Labs portal. Make sure you have an approved developer account and have applied for Labs access to get started with these endpoints.

  [Key differences](https://developer.x.com/content/developer-twitter/en/docs/labs/overview/whats-new) from equivalent v1.1 functionality include:

  * Single endpoint for single object "show" function and batch "lookups"

  * Expansion parameters support the inclusion of additional objects as part of one request (e.g. mentioned users, referenced posts, e.g.)

  * Format parameters support different data projections with more or less verbose payloads

  * Rate limiting is at the app level, regardless of auth method (user context or bearer token)

  Learn more about this launch via our [forum announcement](https://devcommunity.x.com/t/twitter-developer-labs-is-open-to-all-developers/126717).
</Update>

<Update label="Jun 10, 2019" description="X API: Standard v1.1">
  ### Retirement of terms and privacy endpoints

  We have fully retired the Terms of Service and Privacy Endpoints. The current status of our [Privacy Policy](https://x.com/en/privacy) and [Terms of Service](https://x.com/en/tos) is best served by our up-to-date web pages.

  You can learn more about this change via our [forum announcement](https://devcommunity.x.com/t/terms-of-service-and-privacy-endpoints-will-no-longer-serve-content-after-june-10/125714).
</Update>

<Update label="May 21, 2019" description="X API: Standard v1.1">
  ### 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/reference#user)
</Update>

<Update label="May 20, 2019" description="X API: Enterprise v1.1">
  ### Launch of Account Activity Replay API

  Starting today, we are introducing the [Account Activity Replay API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity), a data recovery tool available with the enterprise tier of the [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity)

  The [Account Activity Replay API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) 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#api-reference) server misses events

  Developers can learn more about this API in our [documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity).
</Update>

<Update label="May 6, 2019" description="X API: Standard v1.1">
  ### Support for native media in quotes

  Starting today, native media (photos, videos, and GIFs) can be added to quotes on X, which will be shown as additional media metadata in the entities sections of quote payloads.

  Developers can learn more about this in our [documentation](https://developer.x.com/en/docs/x-api/v1/data-dictionary/object-model/tweet).
</Update>

<Update label="Feb 13, 2019" description="X API: Enterprise v1.1">
  ### Addition of is:reply operator

  Today, the operator is:reply becomes available to use with the [enterprise search APIs](/x-api/enterprise-gnip-2.0/fundamentals/search-api) and the paid version of the [premium search endpoints](https://developer.x.com/content/developer-twitter/en/docs/tweets/search/api-reference/premium-search).

  The is:reply Boolean operator can be used to filter all replies to posts, or to filter out explicit replies that match a rule. This operator functions in the same way as the is:quote operator.

  Remember that, with the Search API, all ‘is:’ and ‘has:’ operators must be used in conjunction with a standalone operator like a keyword or hashtag.

  You can learn more about this operator in the [documentation](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering).
</Update>

<Update label="Feb 6, 2019" description="X API: Premium v1.1">
  ### Changes to expanded URL enrichment

  Today, the expanded URL enrichment will no longer contain the unwound URL object and metadata (including the title and description fields) for URLs linking to posts, Moments, or profiles. Please note that other URLs (to websites, etc.) will continue to be enriched with this metadata, and the url, expanded\_url, and `display_url` will still be available. This change applies to [Decahose](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api), [PowerTrack](/x-api/enterprise-gnip-2.0/powertrack-api), [Historical PowerTrack](https://developer.x.com/content/developer-twitter/en/docs/tweets/batch-historical/overview), and the [Search APIs](https://developer.x.com/en/docs/x-api/v1/tweets/search/overview).
</Update>

<Update label="Nov 29, 2018" description="X API: Enterprise v1.1">
  ### Addition of is:reply operator in PowerTrack

  Today, we are introducing a new operator, is:reply, to help you narrow conversations to those you care about most. You can now filter out replies from your results (in addition to the pre-existing ability to filter out reposts, is:retweet, and Quoted posts, is:quote). This new operator is available today within [PowerTrack](/x-api/enterprise-gnip-2.0/powertrack-api), [Historical PowerTrack](https://developer.x.com/content/developer-twitter/en/docs/tweets/batch-historical/overview), and [Replay](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api).

  The is:reply Boolean operator can be used to filter all replies to posts, or to filter out explicit replies that match a rule. This operator functions in the same way as the is:quote operator.

  You can learn more about this operator in the [documentation](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering).
</Update>

<Update label="Nov 19, 2018" description="X API: Standard v1.1">
  ### Access to apps in Developer Console

  Today, we've added the ability for developers to view and edit their existing [X apps](/resources/fundamentals/developer-apps) via the [X app dashboard](https://developer.x.com/content/developer-twitter/en/apps) on developer.x.com as long as they're logged into their X account. Previously, you could only view and edit your existing X apps on developer.x.com if you had applied or been approved for a [developer account](/resources/fundamentals/developer-portal).

  You still must have an approved developer account to be able to create new X apps.
</Update>

<Update label="Nov 7, 2018" description="X API: Standard v1.1">
  ### Support for video subtitles

  Today, we are announcing that advertisers and publishers are now able to add subtitle files (SRT) to their videos via ads.x.com, Media Studio and our publisher upload API. Subtitles will be viewable on auto-playing video (when no sound is available) on Android and Web. We will release the functionality for iOS in the coming weeks.

  To read more about the new subtitles endpoints, please review their respective API reference pages:

  * [POST media/subtitles-create](/x-api/media/create-media-subtitles)

  * [POST media/subtitles-delete](/x-api/media/delete-media-subtitles)
</Update>

<Update label="Nov 5, 2018" description="X API: Premium v1.1">
  ### Update to Account Activity API endpoint

  Today we are announcing an update to the [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) endpoint, [GET subscriptions/count](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-direct-messages-events-list#get-account-activity-subscriptions-count). To enable greater visibility into your billing details and use of the API, beginning today, you can programmatically pull the number of provisioned subscriptions associated with your Account Activity API instance within the JSON.  This means you can now see both what your provisioned number of subscriptions are, and how close you are to hitting that limit via the GET subscriptions/count API endpoint.

  This update has been documented with the [Account Activity API documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-direct-messages-events-list#get-account-activity-subscriptions-count).
</Update>

<Update label="Oct 22, 2018" description="X API: Standard v1.1">
  ### New rate limits on POST endpoints

  Today we are implementing new app-level rate limits on several of our standard POST endpoints:

  * [POST statuses/update](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/api-reference/post-statuses-update)

  * [POST statuses/retweet/:id](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweets-id)

  * [POST favorites/create](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create)

  * [POST direct\_messages/events/new](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/new-event)

  * [POST friendships/create](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create)

  You can read more about this change in our [forum announcement](https://devcommunity.x.com/t/new-post-endpoint-rate-limit-enforcement-begins-today/115355).
</Update>

<Update label="Oct 10, 2018" description="X API: Standard v1.1">
  ### Update to twitter-text library

  Today, we are announcing an update to the [twitter-text](https://github.com/twitter/twitter-text) library to account for the recent changes to the way that X counts emojis. If an emoji previously counted as more than two characters, its count will now be reduced to just two characters to allow for users to make the most out of their 280 characters.

  You can read more about this change in our [forum announcement](https://devcommunity.x.com/t/new-update-to-the-twitter-text-library-emoji-character-count/114607).
</Update>

<Update label="Sep 17, 2018" description="X API: Standard v1.1">
  ### Retirement of legacy DM endpoints

  We have fully retired the legacy Direct Message endpoints. You can find a list of the retired DM endpoints, as well as their replacements on [this page](https://developer.x.com/content/developer-twitter/en/docs/direct-messages/sending-and-receiving/api-reference).

  You can learn more about this update via our [forum announcement](https://devcommunity.x.com/t/details-and-what-to-expect-from-the-api-deprecations-this-week-on-august-16-2018/110746).
</Update>

<Update label="Sep 11, 2018" description="X API: Standard v1.1">
  ### Changes to DM media access

  Today, we are implementing some changes to the process where you [retrieve attached media from Direct Messages](https://developer.x.com/en/docs/x-api/v1/direct-messages/message-attachments/overview). We will no longer support accessing `media_url` or `media_url_https` via an authenticated [www.x.com](http://www.x.com) session. The request to fetch `media_url_https` MUST always be signed with the user’s access token using OAuth 1.0A.

  You can learn more about this update via our [forum announcement](https://devcommunity.x.com/t/direct-message-api-change-to-how-apps-can-access-images-sent-in-direct-messages/112722).
</Update>

<Update label="Aug 23, 2018" description="X API: Enterprise v1.1">
  ### Retirement of user and site streams

  We have fully retired [User Streams](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#migration-introduction) and [Site Streams](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#migration-introduction).

  You can learn more about this update via our [forum announcement](https://devcommunity.x.com/t/details-and-what-to-expect-from-the-api-deprecations-this-week-on-august-16-2018/110746).
</Update>

<Update label="Aug 20, 2018" description="X API: Enterprise v1.1">
  ### New version of Usage API

  Today we are launching a new version of the Usage API. With this update, we’re making the API more stable by moving to a new system.

  With the system update, users will experience a data "hole" as developers will only be able to pull data back to May 1, 2018. Therefore for the upcoming year, they will be missing out on a few months of historical data (until June 2019).

  A product name is changing within the Usage API from Historical PowerTrack Subscription to Historical PowerTrack 2.0 which will make the product naming consistent with the rest of our user-facing wording. Customers will receive the exact same data in the same format with the update. You will see this change within the products.type JSON object.

  If you have any questions, please reach out to your account manager.
</Update>

<Update label="Aug 16, 2018" description="X API: Standard v1.1">
  ### API deprecations

  The [Account Activity API DM Beta](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#migration-introduction) product was fully retired today.

  The following services and endpoints will experience degraded service starting today:

  * [User Streams](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#migration-introduction)

  * [Site Streams](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#migration-introduction)

  * [GET direct\_messages](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/content/developer-twitter/en/docs/direct-messages/sending-and-receiving/api-reference/get-sent-message)

  * [GET direct\_messages/show](https://developer.x.com/content/developer-twitter/en/docs/direct-messages/sending-and-receiving/api-reference/get-message)

  * [POST direct\_messages/new](https://developer.x.com/content/developer-twitter/en/docs/direct-messages/sending-and-receiving/api-reference/new-message)

  * [POST direct\_messages/destroy](https://developer.x.com/content/developer-twitter/en/docs/direct-messages/sending-and-receiving/api-reference/delete-message)

  User Streams and Site Streams will be fully retired on August 23rd.

  The legacy Direct Messages endpoints will be fully retired on September 17th.

  You can learn more about this update via our [forum announcement](https://devcommunity.x.com/t/details-and-what-to-expect-from-the-api-deprecations-this-week-on-august-16-2018/110746).
</Update>

<Update label="Jul 24, 2018" description="X API: Standard v1.1">
  ### Changes to app creation and rate limits

  As of today, you will no longer be able to create new [X apps](/resources/fundamentals/developer-apps) via [apps.x.com](https://apps.x.com/). You will now be redirected to either your [Developer Console](/resources/fundamentals/developer-portal) account or, if you don't have a Developer Console account yet, to the page where [you can apply](https://developer.x.com/content/developer-twitter/en/apply-for-access).

  We also announced that we will be implementing new app-level rate limits to the following POST endpoints on September 10th, 2018.

  * [POST statuses/update](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/api-reference/post-statuses-update)

  * [POST statuses/retweet:id](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/api-reference/post-statuses-retweet-id)

  * [POST friendships/create](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create)

  * [POST favorites/create](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/api-reference/post-favorites-create)

  * [POST direct\_messages/events/new](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/new-event)

  Finally, we are introducing a new option for people to report suspected violations of our platform policies to you for review.

  You can learn more about all of these updates via our [blog post](https://cli.re/g32qKr).
</Update>

<Update label="Jun 21, 2018" description="X API: Standard v1.1">
  ### App management in Developer Console

  If you have a [Developer Console](/resources/fundamentals/developer-portal) account, you can now create and manage your [X apps](/resources/fundamentals/developer-apps). Please read our [forum post](https://devcommunity.x.com/t/app-creation-and-management-now-available-in-the-Developer%20Console/107723) for more details.
</Update>

<Update label="Jun 12, 2018" description="X API: Standard v1.1">
  ### Changes to Sign in with X and Account Activity

  Today, we started requiring that you register the [callback URLs](/resources/fundamentals/developer-apps#callback-urls) that you use with the Sign in with X process. You can read more about this update [here](https://devcommunity.x.com/t/action-required-sign-in-with-twitter-users-must-whitelist-callback-urls/105342).

  We also announced the addition of the tweet\_delete\_events activity to the Account Activity API. This new activity will be sent for those corresponding deleted events to enable developers to more easily provide a compliant experience for their customers and application users. You can read more about this new activity in our [forum post](https://devcommunity.x.com/t/adding-delete-events-to-the-account-activity-api/106783) or on our [documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity).
</Update>

<Update label="May 25, 2018" description="X API: Standard v1.1">
  ### Updates to terms and policies

  Today, we made some changes to our [Terms of Service](https://x.com/en/tos), [Privacy Policy](https://x.com/en/privacy), and [X Developer Agreement](https://developer.x.com/en/developer-terms/agreement-and-policy) that include privacy, security, and data protection updates. Please read our [forum post](https://devcommunity.x.com/t/upcoming-changes-to-the-developer-platform/104603) for more details.
</Update>

<Update label="May 23, 2018" description="X API: Standard v1.1">
  ### Timezone fields made private

  Today, the timezone values in X user objects became private fields. From here on out, all\* time\_zone and utc\_offset data objects will return as null. Please read our [forum post](https://devcommunity.x.com/t/upcoming-changes-to-the-developer-platform/104603) for more details.
  \* They will continue to be available on the account/settings endpoint, for authenticated users only.
</Update>

<Update label="May 21, 2018" description="X API: Enterprise v1.1">
  ### Removal of Klout data

  Today, we removed all Klout data from post payloads as part of our GDPR updates.
</Update>

<Update label="May 14, 2018" description="X API: Standard v1.1">
  ### Changes to profile background and Account Activity

  Today, we are changing all instances of profile\_background\_image\_url and profile\_background\_image\_url\_https to their default values. Please read our [forum post](https://devcommunity.x.com/t/upcoming-changes-to-the-developer-platform/104603) for more details.

  In addition to the above change, we are adding a new field to the [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) payloads to reference which subscription the activity was delivered for. This JSON object is called for\_user\_id and will include the subscribed user's ID who produced that activity as its value. You can see some examples of this new JSON object in our [account activity objects](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-data-object-structure) page.
</Update>

<Update label="May 10, 2018" description="X API: Standard v1.1">
  ### Changes to quote payload rendering

  Today, we are adding a change to the way that URLs will be rendered in the quote payload.

  We’re adding a new entity called the "quoted\_status\_permalink" entity to ensure the quoted post can be referenced and we will be removing the t.co link from the quoted post "text" field.

  With the new format, the t.co link is no longer appended to the "text" field of the quoted post in the "quoted\_status" object.

  Further, we will no longer put the quoted post t.co url, expanded\_url, and display\_url in the ‘urls’ entity. Instead, these will be added to a new "quoted\_status\_permalink" object with "url", "expanded", and "display" URL attributes. This means that the "quoted\_status\_permalink" object will be reserved for the t.co link back to the quoted post, whereas the "entities.urls" array can be used to identify any links shared within the original post or quote.

  Please read our [forum post](https://devcommunity.x.com/t/updating-how-urls-are-rendered-in-the-quote-tweet-payload/105473) and [updated documentation](https://devcommunity.x.com/t/upcoming-changes-to-the-developer-platform/104603) for more details.
</Update>

<Update label="Apr 30, 2018" description="X for Websites">
  ### Deprecation of X Kit

  The announcement of [X Kit](https://developer.x.com/en/docs/x-for-websites) deprecation, after October 31, 2018 X Kit will no longer be actively maintained.  Please read our [blog post](https://blog.x.com/developer/en_us/topics/tools/2018/discontinuing-support-for-twitter-kit-sdk.html) for more details.
</Update>

<Update label="Apr 24, 2018" description="X API: Standard v1.1">
  ### Platform updates for GDPR

  Today we announced several updates to the platform related to GDPR. Please read our [forum post](https://devcommunity.x.com/t/upcoming-changes-to-the-developer-platform/104603) for more details.
</Update>

<Update label="Mar 1, 2018" description="X API: Enterprise v1.1">
  ### Addition of additional media info object

  The addition of a new object to the post payload – additional\_media\_info object – and also restricting some video details (video\_info) for promoted posts where advertisers have requested we limit video playback to X owned clients. You can find additional information about this change at the following link: [Extended Entities Objects > post with native video](https://developer.x.com/en/docs/x-api/v1/data-dictionary/object-model/extended-entities).
</Update>

<Update label="Feb 1, 2018" description="X API: Premium v1.1">
  ### Launch of premium full-archive search

  Launch of the [premium full-archive search endpoint](https://blog.x.com/developer/en_us/topics/tools/2018/access-the-full-history-of-tweets.html).
</Update>

<Update label="Dec 19, 2017" description="X API: Premium v1.1">
  ### Launch of Account Activity APIs

  Launched both ([All Activities](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#migration-introduction)) and ([Direct Messages](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#migration-introduction)) Standard beta Account Activity APIs, read more about this launch [on our blog](https://blog.x.com/developer/en_us/topics/tools/2017/announcing-more-functionality-to-improve-customer-engagements-on-twitter.html).  Announced User streams & Site streams deprecation and sunset date of Tuesday June 19, 2018.
</Update>

<Update label="Dec 15, 2017" description="X API: Standard v1.1">
  ### Update to twitter-text library

  Version 2.0 of twitter-text is now available [on GitHub](https://github.com/twitter/twitter-text). This update addresses the change in our character limit that was rolled out on November 7th, 2017. To learn more about this update, please [visit our forum](https://devcommunity.x.com/t/shipped-twitter-text-2-0/98577).
</Update>

<Update label="Nov 14, 2017" description="X API: Premium v1.1">
  ### Launch of premium APIs

  Launched the Premium APIs.

  These new APIs build on the quality and stability of our enterprise data platform, and make it available more widely via a tiered pricing model. For the first time, you can start to search across 30 days of posts (instead of the limited 7 days of data on the standard endpoint), and optionally, you can also access our premium enrichments for profile geo, URL expansion, and poll data. Here’s a taste of some of the new features:

  * More posts per request (Sandbox + Premium)

  * A far more rich query language enabling more complex queries (Sandbox + Premium)

  * A counts endpoint that returns time-series counts of posts (Premium)

  * Metadata enrichments, such as expanded URLs and Profile Geo (Premium)

  Read more about this launch [on our blog](https://blog.x.com/developer/en_us/topics/tools/2017/introducing-twitter-premium-apis.html).
</Update>

<Update label="Nov 7, 2017" description="X API: Standard v1.1">
  ### Launch of 280 character posts

  Official launch of 280 character posts in languages where cramming was an issue. Please see our [forum announcement](https://devcommunity.x.com/t/updating-the-character-limit-and-the-twitter-text-library/96425) or official [blog post](https://blog.x.com/official/en_us/topics/product/2017/tweetingmadeeasier.html) for further reference.
</Update>

<Update label="Nov 1, 2017" description="X API: Standard v1.1">
  ### Removal of DM commands in Statuses/Update

  The ability to send Direct Messages via the statuses/update API endpoint has been completely removed, and the `enable_dm_commands` and `fail_dm_commands` parameters will no longer have any effect. Read more about this update [on our forum](https://devcommunity.x.com/t/retiring-legacy-dm-commands-on-the-standard-tweet-api/86653 "on our forum").
</Update>

<Update label="Oct 11, 2017" description="X API: Standard v1.1">
  ### Changes to OAuth login flow

  A change was made to X’s backend OAuth API endpoints which altered the behaviour of the /oauth/authenticate endpoint to match that of the /oauth/authorize endpoint. Read more about this update [on our forum](https://devcommunity.x.com/t/recent-changes-to-twitter-s-oauth-login-flow-and-api-endpoints/94943).
</Update>

<Update label="Oct 10, 2017" description="X API: Enterprise v1.1">
  ### Updates to Engagement API metrics

  The Engagement API was updated to use the same metrics aggregation methodology in use by the X analytics dashboard. Read more about this update [on our forum](https://devcommunity.x.com/t/changes-to-the-engagement-api/94523).
</Update>

<Update label="Oct 1, 2017" description="X API: Standard v1.1">
  ### Changes to DM commands failure

  The default value of the `fail_dm_commands` parameter within the DM statuses/update endpoint has been switched to *true*. All status updates intended as Direct Messages will start to return errors (unless `enable_dm_commands` is *false*, in which case the post will be posted). Read more about this update [on our forum](https://devcommunity.x.com/t/retiring-legacy-dm-commands-on-the-standard-tweet-api/86653).
</Update>

<Update label="Sep 26, 2017" description="X API: Standard v1.1">
  ### Treatment of 280 character tweets

  The response payload for 280 character tweets will be treated the same way as long tweets. Read more about this update [on our forum](https://devcommunity.x.com/t/testing-280-characters-for-certain-languages/94126).
</Update>

<Update label="Sep 11, 2017" description="X API: Standard v1.1">
  ### Addition of additional media info

  Adding new data to the post payload (`additional_media_info object`) and also restricting some video details (`video_info`) for promoted posts where advertisers have requested we limit video playback to X owned clients. You can find additional information about this change at the following link: [Extended Entities Objects > post with native video](https://developer.x.com/en/docs/x-api/v1/data-dictionary/object-model/extended-entities)
</Update>

<Update label="Aug 7, 2017" description="X API: Enterprise v1.1">
  ### End of support for url\_contains operator in 30-Day Search

  30-Day and Full-Archive Search ended support for url\_contains: operator. Deprecation of this operator was announced as part of the Gnip 2.0 migration in August 2016. Any Search query using the url\_contains: Operator will be rejected as invalid.
</Update>

<Update label="Jul 6, 2017" description="X API: Enterprise v1.1">
  ### Upcoming removal of url\_contains operator in search APIs

  The 30-Day Search API (both 30-Day and Full-Archive) will no longer support the url\_contains: operator beginning 30 days from today, or after August 4, 2017 (Support of url\_contains: will actually end with the first deploy after that date). Deprecation of this operator was announced as part of the Gnip 2.0 migration in August 2016. When Operator support is ended, any query using the url\_contains: will be rejected as invalid.
</Update>

<Update label="Jun 2, 2017" description="X API: Standard v1.1">
  ### Retirement of xAuth

  The xAuth authentication mechanism has been removed from all X APIs. Read more about this update [on our forum](https://devcommunity.x.com/t/retirement-of-xauth/88022).
</Update>

<Update label="May 8, 2017" description="X API: Standard v1.1">
  ### HTTP headers forced to lowercase

  All HTTP headers have been forced into lowercase (`content-type`, `x-rate-limit-remaining`, `x-access-level` etc). Read more about this update [on our forum](https://devcommunity.x.com/t/upcoming-http-header-changes/86715).
</Update>

<Update label="May 5, 2017" description="X API: Standard v1.1">
  ### Optional parameters for DM commands

  The optional `enable_dm_commands` parameter to statuses/update will enable applications to remove DM command support early, before the transition period ends. The default value is *true* (i.e. current legacy behavior), but this may be set to *false* to get the new, post-November 1 behavior. The optional fail\_dm\_commands parameter to statuses/update will make DM commands return HTTP 403 (error code 151) from the API when set to *true*. The default value is *false*. Read more about this update [on our forum](https://devcommunity.x.com/t/retiring-legacy-dm-commands-on-the-standard-tweet-api/86653).
</Update>

<Update label="Apr 25, 2017" description="X API: Enterprise v1.1">
  ### Support for emojis in rules

  Rules with emojis are now available in the enterprise Search APIs
</Update>

<Update label="Apr 6, 2017" description="X API: Standard v1.1">
  ### Wider availability of Direct Message APIs

  Access to several new Direct Message APIs are now more widely available. Read more about this update [on our blog](https://blog.twitter.com/developer/en_us/topics/tools/2017/new-apis-to-power-the-future-of-customer-engagement-in-direct-me.html).
</Update>

<Update label="Mar 9, 2017" description="X API: Standard v1.1">
  ### Retirement of MPEG-DASH video support

  MPEG-DASH URLs (.mpd) has been removed from the payload of a post that contains video. Read more about this update [on our forum](https://devcommunity.x.com/t/retiring-mpeg-dash-video-support-on-march-9th-2017/82761).
</Update>

<Update label="Feb 22, 2017" description="X API: Enterprise v1.1">
  ### New enrichments and payload changes

  New Enrichment! Poll Metadata is now available through our enterprise APIs. See the [documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#migration-introduction) for more details.

  New payload field: Image Alt-Text (description) field may be present in the entities.media\[] and extended\_entities.media\[] section of the payload if a user chooses the "Add description" option when adding a photo to a post. This is available in enriched native format only.

  Default payload format: Newly created streams on Gnip products will now default to original format JSON.
</Update>

<Update label="Jan 23, 2017" description="X API: Enterprise v1.1">
  ### Updates to Historical PowerTrack and Replay API

  Historical PowerTrack API & Replay API

  * quote filtering is now supported

  * Quoted posts are now fully rehydrated within HPT and Replay post payloads
</Update>

<Update label="Jan 17, 2017" description="X API: Enterprise v1.1">
  ### New payload fields for counts

  New payload fields: quote\_count and reply\_count are now available in native enriched format payloads across Realtime and Historical APIs
</Update>

<Update label="Dec 20, 2016" description="X API: Enterprise v1.1">
  ### Support for geo operators in Full-Archive Search

  Full-Archive Search API (FAS):

  * Added support for additional geo operators:

  * place:

  * place\_country:

  * has:profile\_geo:

  * profile\_country:

  * profile\_region:

  * profile\_locality:
</Update>

<Update label="Dec 5, 2016" description="X API: Enterprise v1.1">
  ### Rule management by ID in PowerTrack

  Rule management (GET and DELETE) by Rule ID is now available for PowerTrack 2.0 and PowerTrack Replay 2.0
</Update>

<Update label="Nov 10, 2016" description="X API: Enterprise v1.1">
  ### Support for geo operators in 30-Day Search

  30-Day Search API:

  * Added support for additional geo operators:

  * place:

  * place\_country:

  * has:profile\_geo:

  * profile\_country:

  * profile\_region:

  * profile\_locality:
</Update>


# Developer Guidelines
Source: https://docs.x.com/developer-guidelines

Developer policies and guidelines for the X API, covering allowed use cases, restricted behaviors, compliance requirements, and best practices for apps.

<Warning>
  **Violations can result in app suspension, API access revocation, or permanent account bans.** Always review the official policies before building.
</Warning>

<CardGroup>
  <Card title="Developer Agreement" icon="file-contract" href="https://docs.x.com/developer-terms/agreement">
    Binding legal terms for API access
  </Card>

  <Card title="Developer Policy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-check.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=768533bde161ac68862de87449f011c3" href="https://docs.x.com/developer-terms/policy">
    Rules for building on X
  </Card>

  <Card title="Automation Rules" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-ai-agents.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=53171c3a2a9432187cf705d13e24651b" href="https://help.x.com/en/rules-and-policies/x-automation">
    Specific rules for bots
  </Card>

  <Card title="Restricted Use Cases" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-block.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=702a65b4001948aebcc42635b8e2eac7" href="https://docs.x.com/developer-terms/restricted-use-cases">
    Prohibited activities
  </Card>
</CardGroup>

***

## Quick check: is my app allowed?

Before building, ask yourself these questions. If you answer **"no"** to any of them, your app likely violates X's policies.

<CardGroup>
  <Card title="User Initiated?" icon="hand-pointer">
    For interactions, did the user **explicitly request** it?
  </Card>

  <Card title="Transparent?" icon="tag">
    Is your app's purpose and behavior **clear to users**? (Automated accounts must be labeled.)
  </Card>

  <Card title="Easy Opt-Out?" icon="right-from-bracket">
    Can users **easily opt out** of any ongoing interactions?
  </Card>

  <Card title="Real Value?" icon="gem">
    Does it provide **real value** beyond self-promotion?
  </Card>

  <Card title="Official API Only?" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219">
    Are you **only using the official API** (not scraping/browser automation)?
  </Card>

  <Card title="Within Limits?" icon="gauge">
    Are you **within rate limits** and respecting usage policies?
  </Card>
</CardGroup>

<Tip>
  When in doubt, ask: "Would a user be happy with this experience?" If not, reconsider your approach.
</Tip>

***

## Common scenarios: allowed or not?

Real-world examples to help you understand what's permitted. **These rules apply to all apps**—whether you're building a bot, mobile app, web integration, browser extension, analytics dashboard, or any other tool that uses the X API.

<Tabs>
  <Tab title="Content & Posting">
    | Scenario                                                              |                                                                                      Allowed?                                                                                     | Why                                                |
    | --------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -------------------------------------------------- |
    | Automated account posts scheduled content (news, weather, quotes)     | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | Informational, no unsolicited mentions             |
    | App posts RSS feed updates on behalf of user                          | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | Helpful broadcasting                               |
    | Alert service posts earthquake/disaster notifications                 | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | Public safety value                                |
    | Sports app posts game updates to user's timeline                      | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | Informational                                      |
    | App posts stock/crypto prices on schedule                             | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | Informational, no manipulation                     |
    | App posts identical content across multiple accounts                  |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Spam / platform manipulation                       |
    | App posts to trending topics to gain visibility                       |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Trend manipulation                                 |
    | Multiple city-specific alert accounts (e.g., @WeatherNYC, @WeatherLA) | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | Allowed—non-duplicative, location-specific content |
  </Tab>

  <Tab title="Replies & Mentions">
    | Scenario                                               |                                                                                      Allowed?                                                                                     | Why                                                                         |
    | ------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | --------------------------------------------------------------------------- |
    | App responds to @mentions asking for help              | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | User-initiated request                                                      |
    | App auto-replies to anyone mentioning a keyword        |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Unsolicited interaction                                                     |
    | App auto-replies to users who reply to your post       | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | User engaged first—limit 1 reply. [Conditions apply](#gray-areas-explained) |
    | AI-powered app generates and posts replies             |      <Icon icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" />     | Requires **prior approval** from X                                          |
    | App replies with "follow me for more!" to random users |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Spam, unsolicited                                                           |
    | Utility app that unrolls threads when mentioned        | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | User-initiated utility                                                      |
  </Tab>

  <Tab title="Direct Messages">
    | Scenario                                                  |                                                                                      Allowed?                                                                                     | Why                                                                     |
    | --------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ----------------------------------------------------------------------- |
    | App responds to DMs with helpful info                     | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | User-initiated                                                          |
    | App sends affiliate links when user DMs first             | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | User-initiated—must disclose. [Conditions apply](#gray-areas-explained) |
    | App auto-DMs new followers with welcome message           |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Unsolicited, even to followers                                          |
    | App bulk-DMs users about a product launch                 |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Spam                                                                    |
    | Support integration asks "How can I help?" after user DMs | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | User-initiated conversation                                             |
  </Tab>

  <Tab title="Engagement">
    | Scenario                                              |                                                                                      Allowed?                                                                                     | Why                                                                                    |
    | ----------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -------------------------------------------------------------------------------------- |
    | Third-party app lets user tap a like button on a post | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | User-initiated through the app                                                         |
    | App auto-likes posts containing a hashtag             |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Automated, not user-initiated                                                          |
    | Mobile app has "auto-like" feature for selected users |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Automated, not user-initiated                                                          |
    | Service sells likes or offers "bulk like" packages    |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Selling engagement is prohibited                                                       |
    | App reposts content from a curated list               | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | OK for informational purposes, no bulk spam. [Conditions apply](#gray-areas-explained) |
    | Growth tool bulk-follows accounts to grow audience    |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Manipulation                                                                           |
    | App follows back anyone who follows it                |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Bulk/aggressive following                                                              |
    | App adds users to lists in bulk                       |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Indiscriminate list manipulation                                                       |

    <Warning>**Likes must be directly initiated by the authenticated user.** Automated, bulk, or indiscriminate liking — including auto-liking by keyword, hashtag, user, or schedule — is prohibited. Apps may not offer "auto-like" features or sell likes as a service. This applies to all apps—bots, mobile apps, browser extensions, or any integration.</Warning>
  </Tab>

  <Tab title="Promotions & Commerce">
    | Scenario                                             |                                                                                      Allowed?                                                                                     | Why                                                                                         |
    | ---------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------- |
    | App sends product recommendations when asked         | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | User-initiated                                                                              |
    | App replies to random posts with affiliate links     |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Unsolicited spam                                                                            |
    | Giveaway app that requires follows/retweets to enter |      <Icon icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" />     | Risky—can be seen as engagement manipulation                                                |
    | Service selling likes/follows/retweets               |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Strictly prohibited                                                                         |
    | Tip service that sends crypto when user requests     | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | User-initiated—comply with financial regulations. [Conditions apply](#gray-areas-explained) |
  </Tab>

  <Tab title="Data & Research">
    | Scenario                                          |                                                                                      Allowed?                                                                                     | Why                               |
    | ------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | --------------------------------- |
    | App tracks brand mentions for analytics dashboard | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | Valid use case                    |
    | App scrapes X via browser automation (not API)    |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | **Permanent suspension**—API only |
    | App stores X data to train AI/ML models           |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Prohibited (except Grok)          |
    | App redistributes >1.5M posts in 30 days          |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Exceeds redistribution limits     |
    | App benchmarks X performance vs competitors       |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | Prohibited competitive analysis   |
    | Academic research on public conversation trends   | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | Valid with proper data handling   |

    <Danger>
      **Non-API automation (scraping, browser automation) results in permanent suspension.** Always use the official X API.
    </Danger>
  </Tab>
</Tabs>

***

## Prohibited activities

<Warning>
  These activities will get your app suspended or permanently banned. There are no exceptions.
</Warning>

| Category                      | Examples                                                                             |
| ----------------------------- | ------------------------------------------------------------------------------------ |
| **Spam & Manipulation**       | Identical content across accounts, fake engagement, trend manipulation, bulk posting |
| **Unsolicited Outreach**      | Auto-replies to random users, bulk DMs, uninvited @mentions                          |
| **Deceptive Bots**            | Impersonating humans, hiding bot identity, misleading links/redirects                |
| **Engagement Selling**        | Apps that sell likes, follows, retweets, or views                                    |
| **Rate Limit Abuse**          | Exceeding limits, designing apps that encourage overuse                              |
| **Non-API Automation**        | Browser scripting, scraping, any automation outside official API                     |
| **Account Farms**             | Multiple accounts for same duplicative purpose                                       |
| **Surveillance**              | Profiling, tracking, or monitoring users without consent                             |
| **Unauthorized AI Training**  | Using X data to train ML models (Grok excepted)                                      |
| **Sensitive Data Derivation** | Inferring health, political, religious, or other sensitive attributes                |
| **Excessive Redistribution**  | Sharing >1.5M Post IDs per 30-day period                                             |

***

## Automation rules

<Note>
  This section applies specifically to **automated accounts** (bots) that post, reply, or interact on behalf of users. If you're building an analytics dashboard, research tool, or other non-automated app, these labeling requirements don't apply to you—but the technical restrictions still do.
</Note>

### Requirements for automated accounts

All automated accounts using the X API must meet these requirements:

<Steps>
  <Step title="Enable the 'Automated' profile label">
    This label appears under your bot's name/handle on its profile. Enable it in your app settings to ensure transparency.
  </Step>

  <Step title="Disclose in bio">
    State clearly that it's a bot and who operates it. Example: *"Bot by @yourcompany"* or *"Automated account managed by Example Inc."*
  </Step>

  <Step title="Link to a human-managed account">
    For accountability and contact purposes, your bot must be associated with a human-managed account.
  </Step>

  <Step title="Honor opt-out requests immediately">
    If a user says "stop," stop. Implement keyword detection for common opt-out phrases.
  </Step>

  <Step title="Use only the official X API">
    No scraping, browser automation, or unofficial methods. Violations result in permanent suspension.
  </Step>

  <Step title="Stay within rate limits">
    Don't try to circumvent or abuse rate limits. Design your app to handle limits gracefully.
  </Step>
</Steps>

### Automated actions: what's allowed?

| Action              |                                                                                      Allowed?                                                                                     | Rules                                                                                        |
| ------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -------------------------------------------------------------------------------------------- |
| **Post tweets**     | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | No unsolicited @mentions. No identical cross-posting.                                        |
| **Reply to users**  |      <Icon icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" />     | Only if user engaged first. Max **1 reply per interaction**.                                 |
| **Send DMs**        |      <Icon icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" />     | Only after user DMs you first. Easy opt-out required.                                        |
| **Like posts**      |      <Icon icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" />     | Must be directly user-initiated. Auto-liking, bulk liking, and selling likes are prohibited. |
| **Repost**          |      <Icon icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" />     | OK for informational/entertainment. No bulk spam.                                            |
| **Quote tweet**     |      <Icon icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" />     | Same rules as repost—no spam or manipulation.                                                |
| **Follow/Unfollow** |  <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45" /> | No bulk, aggressive, or automated following.                                                 |
| **Add to Lists**    |      <Icon icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" />     | No bulk or indiscriminate additions.                                                         |
| **Bookmark**        | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | Fine for personal/automated use.                                                             |
| **Search/Read**     | <Icon icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59" /> | Standard use within rate limits.                                                             |

***

## Gray areas explained

Many developers have questions about edge cases. Here's guidance on common gray areas.

<AccordionGroup>
  <Accordion title="Affiliate Links & Promotions" icon="link">
    <Check>
      **Allowed if:**

      * User explicitly requests it (e.g., DMs asking for a recommendation)
      * You clearly disclose the affiliate/sponsored relationship
      * Links are not misleading (no deceptive redirects)
    </Check>

    <Warning>
      **Not allowed if:**

      * You auto-reply to random posts with affiliate links
      * You DM users who didn't ask
      * You hide the commercial relationship
    </Warning>
  </Accordion>

  <Accordion title="AI-Generated Content & Replies" icon="microchip-ai">
    * **Requires prior approval from X** before deployment
    * Must still follow all rules (no unsolicited mentions, properly labeled)
    * Contact X via the [Policy Support form](https://help.x.com/forms/platform) before launching
    * Even with approval, cannot impersonate humans

    <Warning>Deploying AI-generated replies without approval is a violation, even if the content itself is helpful.</Warning>
  </Accordion>

  <Accordion title="Welcome Messages to New Followers" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-envelope.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=fbd38dbcd64d8688d3c9912ac30c4621">
    **Not allowed** as automated DMs—this counts as unsolicited contact, even though they followed you.

    **Alternatives:**

    * Pinned tweet welcoming new followers
    * Bio with intro info and links
    * Auto-reply only if they DM you first
  </Accordion>

  <Accordion title="Multiple Accounts / Regional Bots" icon="globe">
    <Check>
      **Allowed if:**

      * Each account serves **non-duplicative** purposes (e.g., @EarthquakeJP, @EarthquakeCA)
      * Content is meaningfully different (location-specific, language-specific)
      * Not used to bypass limits or amplify the same message
    </Check>

    <Warning>
      **Not allowed if:**

      * Posting identical/similar content across accounts
      * Created to evade suspensions or rate limits
    </Warning>
  </Accordion>

  <Accordion title="Customer Support Automation" icon="headset">
    <Check>
      **Allowed if:**

      * User initiates (mentions you, DMs you, or explicitly opts in)
      * Clear opt-out mechanism exists
      * Responses are helpful, not promotional
      * Includes privacy policy link in DMs
    </Check>

    <Warning>
      **Not allowed if:**

      * You reach out to users who complained publicly (unsolicited)
      * Responses are primarily promotional
    </Warning>
  </Accordion>

  <Accordion title="Giveaways & Contests" icon="gift">
    **Proceed with caution:**

    * Requiring follows/retweets as entry can be seen as engagement manipulation
    * Must comply with [X's contest guidelines](https://help.x.com/en/rules-and-policies/x-contest-rules)
    * Don't use multiple accounts to amplify
    * Ensure prizes are real and delivered

    <Tip>Consider entry methods that don't require engagement actions, like replying with a specific phrase.</Tip>
  </Accordion>
</AccordionGroup>

***

## Data handling and display requirements

<Warning>
  These requirements are legally binding under the Developer Agreement. Non-compliance can result in termination and legal action.
</Warning>

### Content deletion

You must delete X Content from your systems when requested:

| Trigger                           | Deadline                                      |
| --------------------------------- | --------------------------------------------- |
| X requests deletion               | **24 hours**                                  |
| User requests deletion            | **24 hours**                                  |
| Content is suspended/removed on X | **24 hours**                                  |
| Your API access is terminated     | **10 business days** (must delete all X data) |

<Tip>
  Use [Compliance Firehose](https://docs.x.com/x-api/compliance/streams) to receive real-time deletion events and stay compliant automatically.
</Tip>

### Off-X matching

**Off-X matching** means associating X data (username, user ID, posts) with off-platform identifiers (your customer database, email lists, device IDs, etc.).

<Check>
  **Allowed with express opt-in consent:**

  * User explicitly agrees to link their X account with your service
  * Clear disclosure of what data will be matched and why
</Check>

<Warning>
  **Without consent, you may only match:**

  * Information the user directly provided to you
  * Publicly available X data (posts, bio, display name, username)
  * Public resources like professional directories

  **Never match if it would surprise the user.**
</Warning>

### Sensitive data

<Danger>
  You **cannot** derive, infer, or store information about X users in these categories:
</Danger>

| Category                        | Examples                                     |
| ------------------------------- | -------------------------------------------- |
| **Health**                      | Medical conditions, pregnancy, disabilities  |
| **Financial status**            | Negative financial condition, credit issues  |
| **Political**                   | Party affiliation, political beliefs, voting |
| **Racial/Ethnic**               | Origin, ethnicity                            |
| **Religious/Philosophical**     | Beliefs, affiliations                        |
| **Sex life/Sexual orientation** | Any inference about sexuality                |
| **Trade union**                 | Membership or affiliation                    |
| **Criminal**                    | Alleged or actual criminal activity          |

<Note>
  **Exception:** Aggregate analysis without storing personal identifiers (no user IDs, usernames, or linkable data) may be allowed for research purposes, subject to applicable laws.
</Note>

### Displaying X content

| Requirement          | Details                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| **Attribution**      | Use proper X branding. Follow [Brand Guidelines](https://about.x.com/en/who-we-are/brand-toolkit).       |
| **No alterations**   | Only modify for display formatting (resizing). Don't edit content, remove timestamps, or strip metadata. |
| **No iframes**       | Don't display X Content in iframes. Use official embeds or render directly.                              |
| **Respect removals** | Remove content within 24 hours if deleted on X.                                                          |

***

## Technical restrictions

<Note>
  These limits apply to all developers. Exceeding them can result in rate limiting or suspension.
</Note>

| Restriction                         | Limit                                                                     |
| ----------------------------------- | ------------------------------------------------------------------------- |
| **Post ID redistribution**          | Max 1.5M Post IDs per 30-day period to any single entity                  |
| **Hydrated content redistribution** | Max 50,000 hydrated Posts or Users per recipient per day                  |
| **Rate limits**                     | Vary by endpoint and tier—[see API docs](/x-api/fundamentals/rate-limits) |
| **AI/ML training**                  | Prohibited (except for Grok)                                              |
| **Non-API access**                  | Prohibited—scraping and browser automation = permanent ban                |
| **Competitive benchmarking**        | Prohibited—can't measure X performance vs. competitors                    |
| **Multiple apps for same use case** | Prohibited—don't create duplicate apps to bypass limits                   |

### Special use cases

| Use Case                             | Requirement                                                      |
| ------------------------------------ | ---------------------------------------------------------------- |
| **Government use**                   | Requires Enterprise tier                                         |
| **Commercial use**                   | Requires appropriate paid tier; free tier is non-commercial only |
| **Academic research**                | May have different redistribution limits; contact X for details  |
| **EU Digital Services Act research** | Specific non-commercial research provisions available            |

***

## Security and compliance

Your obligations as a developer:

<AccordionGroup>
  <Accordion title="Security Requirements" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055">
    * Use **industry-standard security** practices to protect X data
    * Never share your API credentials or tokens
    * Store credentials securely (environment variables, secret managers—not in code)
    * Implement proper authentication in your apps
  </Accordion>

  <Accordion title="Breach Notification" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bell.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=5e0b3dcfbb39ba3d4619931d7cd927d1">
    If you experience a security breach involving X data:

    * **Notify X immediately**
    * Take steps to mitigate the breach
    * Cooperate with X's investigation
  </Accordion>

  <Accordion title="Confidentiality" icon="lock">
    * Treat any non-public information from X as confidential
    * Don't disclose API rate limits, internal X data, or non-public features
    * Don't use confidential info for competitive purposes
  </Accordion>

  <Accordion title="Audit Rights" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834">
    * X may audit your compliance **up to once per year**
    * You must provide reasonable access and documentation
    * Keep records of how you use X data
  </Accordion>
</AccordionGroup>

***

## Summary: do's and don'ts

<Tabs>
  <Tab title="Do" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59">
    **For Automated Accounts:**

    * Enable "Automated" profile label
    * Disclose operator in bio
    * Wait for users to initiate interaction
    * Provide easy opt-out
    * Get approval for AI-generated replies

    **For All Apps:**

    * Use only the official X API
    * Respect rate limits and redistribution limits
    * Delete content within 24 hours when requested
    * Get opt-in consent for off-X matching
    * Use proper attribution when displaying X Content
    * Secure your credentials and notify X of breaches
    * Keep records of your X data usage
  </Tab>

  <Tab title="Don't" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-close-circle-lg.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=acd38e6d809cbe13214e52f85f30eb45">
    **For Automated Accounts:**

    * Hide automated nature
    * Send unsolicited DMs, replies, or @mentions
    * Ignore "stop" requests
    * Post identical content across accounts
    * Auto-like, bulk-like, or sell likes (likes must be user-initiated)

    **For All Apps:**

    * Scrape or use browser automation
    * Train AI/ML models on X data (except Grok)
    * Derive sensitive user data (health, politics, religion, etc.)
    * Match X data to off-platform IDs without consent
    * Display X Content in iframes
    * Redistribute more than limits allow
    * Create multiple apps for the same use case
    * Use X data for surveillance or user tracking
  </Tab>
</Tabs>


# Policies and agreements
Source: https://docs.x.com/developer-terms

X developer policies, agreements, and display requirements, covering the Developer Agreement, Developer Policy, Ads API agreement, and restricted use cases.

## Overview

Developer use of X materials and content is subject to and governed by our Developer Policy and agreements.

<div>
  <Card title="Developer Agreement" icon="gavel" href="/developer-terms/agreement">
    <div>
      <Button href="/developer-terms/agreement">View</Button>
    </div>
  </Card>

  <Card title="Developer Policy" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/developer-terms/policy">
    <div>
      <Button href="/developer-terms/policy">View</Button>
    </div>
  </Card>

  <Card title="Ads API Agreement" icon="gavel" href="/developer-terms/ads-api-agreement">
    <div>
      <Button href="/developer-terms/ads-api-agreement">View</Button>
    </div>
  </Card>

  <Card title="X Developer PPU Agreement" icon="gavel" href="/developer-terms/ppu-agreement">
    <div>
      <Button href="/developer-terms/ppu-agreement">View</Button>
    </div>
  </Card>

  <Card title="Restricted use cases" icon="user-xmark" href="/developer-terms/more-on-restricted-use-cases">
    <div>
      <Button href="/developer-terms/restricted-use-cases">View</Button>
    </div>
  </Card>

  <Card title="Geo guidelines" icon="earth-americas" href="/developer-terms/geo-guidelines">
    <div>
      <Button href="/developer-terms/geo-guidelines">View</Button>
    </div>
  </Card>

  <Card title="Display requirements" icon="display" href="/developer-terms/display-requirements">
    <div>
      <Button href="/developer-terms/display-requirements">View</Button>
    </div>
  </Card>
</div>


# Ads API Agreement
Source: https://docs.x.com/developer-terms/ads-api-agreement

The X Ads API Agreement governs use of X advertising endpoints, including allowed integrations, restrictions, and obligations for advertising partners.

We have updated our Ads API Agreement. The changes below are effective as of February 23, 2025.

## X Ads Products and Services Agreement

**Effective: February 23, 2025**

This X Ads Products and Services Agreement (the “**Agreement**”) is made and entered into by and between the entity identified in the “X Ads API Program” application form submitted to X by such entity (or its authorized representative) (referred to herein as “**Company**”) and X Corp., if Company is outside of the European Union, EFTA States, or the United Kingdom, including if your Company is in the United States of America, or X Internet Unlimited Company, if Company is in the European Union, EFTA States, or the United Kingdom, on behalf of itself and its Affiliates (as defined below) (in either case, “**X**”) and governs Company’s access to and use of the Ad Products (as defined below). As used herein, “**Affiliate**” means any other entity that directly or indirectly controls, is controlled by, or is under common control with X.

PLEASE READ THE TERMS AND CONDITIONS OF THIS AGREEMENT CAREFULLY, INCLUDING, WITHOUT LIMITATION, ALL EXHIBITS ATTACHED HERETO AND ANY LINKED TERMS AND CONDITIONS APPEARING OR REFERENCED BELOW, WHICH ARE HEREBY MADE PART OF THIS AGREEMENT. BY CHECKING THE BOX LABELED “Yes, I Agree” AND CLICKING “SUBMIT” (OR LANGUAGE THAT IS THE EQUIVALENT OF “Yes, I Agree” SUCH AS, FOR EXAMPLE ONLY, “I Accept”) OR USING THE X MATERIALS, COMPANY IS AGREEING THAT COMPANY HAS READ, AND THAT COMPANY AGREES TO COMPLY WITH AND TO BE BOUND BY, THE TERMS AND CONDITIONS OF THIS AGREEMENT. IF COMPANY DOES NOT AGREE TO BE BOUND BY THIS AGREEMENT, THEN COMPANY MAY NOT ACCESS OR OTHERWISE USE THE X MATERIALS. THIS AGREEMENT IS EFFECTIVE AS OF THE EARLIER OF: (I) THE DATE COMPANY CHECKS “Yes, I Agree” AND CLICKS “SUBMIT” TO ACCEPT THIS AGREEMENT, OR (II) THE FIRST DATE THAT COMPANY ACCESSES THE X MATERIALS (“**EFFECTIVE DATE**”). IF AND TO THE EXTENT, HOWEVER, THAT COMPANY’S APPLICATION TO ACCESS AND USE THE X MATERIALS IS NOT APPROVED BY X (IN ITS SOLE AND ABSOLUTE DISCRETION), THIS AGREEMENT WILL BE NULL, VOID AND OF NO EFFECT. IF YOU ARE AN INDIVIDUAL REPRESENTING COMPANY, YOU ACKNOWLEDGE, REPRESENT, AND WARRANT, THAT YOU (A) HAVE READ AND UNDERSTAND THIS AGREEMENT, (B) HAVE THE APPROPRIATE AUTHORITY TO ACCEPT THIS AGREEMENT ON BEHALF OF COMPANY, AND (C) YOU AGREE, ON BEHALF OF COMPANY, TO THE TERMS OF THIS AGREEMENT. YOU MAY NOT USE THE X MATERIALS AND MAY NOT ACCEPT THIS AGREEMENT IF YOU DO NOT HAVE THE LEGAL AUTHORITY TO BIND COMPANY, ARE NOT OF LEGAL AGE OR ARE OTHERWISE UNABLE TO FORM A BINDING CONTRACT WITH X, OR YOU ARE BARRED FROM USING OR RECEIVING THE X MATERIALS UNDER APPLICABLE LAW.

### 1. Introduction; Scope; Individual Product Terms.

**1.1 Introduction.** X maintains, operates, and offers a suite of products and services that enable various functionalities for X’s advertising partners. The specific products, services and programs (each, an “**Individual Product**”) that enable or are related to these functionalities are: (i) the X Ads API Program (as further described in [Exhibit A](#Exhibit-A)); and (ii) X’s Custom Audiences Program (as further described in [Exhibit B](#Exhibit-B)). Collectively, these Individual Products are referred to herein as the “**Ads Products**”. This Agreement governs the use of, and/or access to, the Ads Products collectively, and the Individual Products individually. In addition, to the extent that Company participates in the X Marketing Partner (“**TMP**”) program in connection with an Ads Product covered under this Agreement, the terms and conditions set forth in [Exhibit C](#Exhibit-C) will apply to Company.

**1.2 Scope.** Subject to this Agreement, during the Term, Company may access and use the specific Individual Products to which X has granted or provided Company with access. Company is under no obligation to use any or all of the Individual Products to which X has granted or provided Company with access, and X is under no obligation to provide (nor continue to provide) Company with the use of, and/or access to, any given Individual Product or feature of the Ads Products. X may grant or deny use of and/or access to any given Individual Product, or any feature thereof, at any time at X’s sole discretion. To the extent that Company accesses or uses any feature of the Ads Products, the terms of this Agreement will govern any such access or use. For the avoidance of doubt, this Agreement shall solely govern Company’s use of the Ads Products described herein. Access and use by Company of any data, content or other materials provided (directly or indirectly) by X to Company under a separate agreement and/or in connection with a separate X program shall be governed wholly by the terms and conditions of such separate agreement and/or program (and not the terms and conditions of this Agreement), unless otherwise mutually agreed in writing by X and Company.

**1.3 Individual Product Terms.** Each Individual Product may include specific terms and conditions that, in addition to and without limitation of the terms of this Agreement, will be applicable to the extent that Company accesses or uses the given Individual Product. Company’s access to any given Individual Product and/or the associated X Materials (as defined below) is conditioned upon Company’s acceptance of, and compliance with, the Individual Product Terms and any technical limitations on access, calls, and use of the Individual Products. The Individual Product Terms are attached hereto as [Exhibit A](#Exhibit-A) and [Exhibit B](#Exhibit-B). X may establish and modify such Individual Product policies or terms in X’s sole discretion, as set forth in Section 15.15 below.

### 2. Definitions.

**2.1** "**Campaign**" means a desktop, mobile website, or mobile application advertising campaign, or fraction thereof.

**2.2** "**Client**" means a X advertiser (who is also a Company customer) that utilizes one (1) or more of the Ads Products, as approved by X in each instance.

**2.3** "**Company Marks**" means Company’s name and any Company logos, trademarks and/or service marks supplied by Company to X for use hereunder (or otherwise authorized by Company for X’s use hereunder).

**2.4** "**Company Materials**" means any Company data, deliverables, or user content provided by Company to X via the Ads Products.

**2.5** "**Company Service**" means Company’s websites, applications and other offerings that display or otherwise use X Materials or aspects thereof.

**2.6** "**Data**" means metrics, data and any other information and/or content X makes available to Company, including any results, usage statistics, data or other information (in the aggregate or otherwise) derived from analyzing or using any of the foregoing.

**2.7** "**End Users**" means an employee or authorized agent of a Client who uses the Ads Products on behalf of such Client.

**2.8** "**Marks**" means the X Marks and/or Company Marks, as the case may be (based on context).

**2.9** "**Materials**" means X Materials and/or Company Materials, as the case may be (based on context).

**2.10** "**Personal Data**" means data relating to a living individual who is or can be identified either from the data or from the data in conjunction with other information that is in, or is likely to come into, the possession of the data controller.

**2.11** "**X Ads**" means X advertising products and services, including the placement of advertisements on the X Network.

**2.12** "**X Code**" means computer code that will call (at a minimum) a X server, developed by X and provided to Company.

**2.13** "**X Marks**" means X’s name and any X logos, trademarks and/or service marks supplied by X to Company for use hereunder (or otherwise authorized by X for Company’s use hereunder).

**2.14** "**X Materials**" means any X data, deliverables, or user content (including derivatives thereof) generated by X, and any X data, deliverables, or user content (including derivatives thereof) generated, collected or developed by X, or that is provided or made available to Company by X pursuant to this Agreement, including any data derived from, based upon, or arising out of, Company’s partnership with X, or any device-level data, or any conversion, engagement, tracking or targeting data that Company or any X-approved third party collects, infers, derives, or obtains from or in connection with Company’s X advertising campaigns. For clarity and without limitation, “X Materials” includes the X Ads API (as defined in [Exhibit A](#Exhibit-A)), X Code, Data, the Ads Products, and any X user ID used to create a Custom Audience (defined below).

**2.15** "**X Network**" means the network of advertising channels, including all forms of media, applications, and devices, through which X may distribute ads, in any medium now known or hereafter developed.

**2.16** "**X Marketing Partners Program**" means the partnership and branding program offered by X, as further described in [Exhibit C](#Exhibit-C).

**2.17** "**X Service**" means: (i) real-time content and information services operated by X, (ii) the technology and systems that enable such services, which includes, collectively, the consumer and advertising products and services currently provided by X or at its websites, and X-owned, operated and/or controlled mobile applications and social plug-ins and APIs, including, without limitation, the Measurement Code, any HTML tags or other codes, internet portals, dashboards, systems and analytic tools and related services, and (iii) all other products or services offered by X and its Affiliates, including (without limitation and for example only) the X Audience Platform and Data & Enterprise Solutions.

### 3. X Ads/Campaign Management; Liability Assumption.

**3.1 X Ads/Campaign Management.** Company may have access to one or more Individual Products that will allow Company, in Company’s sole discretion and/or at the direction of Company’s Clients, to optimize, modify, manage, initiate or manipulate X Ads on the X Network, or otherwise make ad management and targeting decisions (referred to herein as “**Campaign Management**”). If Company accesses or uses any such Individual Products: (a) Company must promptly provide any advertising materials it intends to post to the X Network; and (b) Company authorizes X to place Company and/or Client’s advertising materials on any content or property available through the applicable Individual Product, whether such content or property is provided on the X Network or through a third party. Company will obtain the necessary licenses and authorizations from the applicable Client for Company to use such advertising materials on behalf of such Client. Company is not required to use any Individual Product that permits Campaign Management, but if Company uses any such products, services or features, then Company hereby assumes any and all risk, and accepts any and all responsibility and liability arising out of or in connection with Company’s Campaign Management, including but not limited to: (i) audience creation and selection, data entry errors, tactic selection, and associated inventory, data, and other third-party costs; (ii) properties to which any ads provided by Company directs viewers (e.g. landing pages) and any redirects therefrom; (iii) services and products advertised in any landing pages; and (iv) any associated Company Materials including without limitation, the advertising materials, technology, and/or creative provided to X. Company hereby acknowledges and agrees that X shall bear no responsibility or liability in connection with Company’s Campaign Management. Without limiting the generality of the foregoing, X shall not be responsible, and Company shall be solely responsible, for training Company’s personnel in Campaign Management and the Ads Products functionality.

**3.2 Binding of Clients to these Terms; Liability Assumption.** If Company accesses or uses the Ads Products (or any aspect thereof, including by Campaign Management) on behalf of Clients or any other third parties, Company warrants that it: (i) is authorized to act on behalf of such Clients or other third parties, and has bound such Clients or other third parties to the applicable Our Policies (as defined in Section 6 below), including the applicable X Master Services Agreement (“**MSA**”), which shall govern all purchases of X Ads made by Company, and the terms of this Agreement that apply to the access and use of the applicable Ads Products (or any aspect thereof) and (ii) will be responsible for their compliance with, and liable for their breach thereof.

### 4. Privacy.

**4.1 Direct Data Gathering.** Company represents and warrants that (i) in the event Company is collecting data from users directly (including, without limitation, on or through the Company Service), it has provided such users with legally-sufficient notice (including, without limitation, by conspicuously posting a legally-sufficient privacy policy from all websites, mobile applications, and other services from which data from users are collected and/or made available to X that complies with all applicable laws and regulations, discloses the fact that third parties collect information about users’ activities on or through the relevant websites, mobile applications, and other services (e.g., browsing or shopping) for interest-based advertising purposes, and provides users with legally sufficient instructions for such users to opt out of interest-based advertising); (ii) it has obtained all legally-required informed consent from such users, including regarding Company’s use of cookies and/or tracking pixels in connection with such data collection; and (iii) the Company Materials do not contain or relate to, and any audience data provided, made accessible, or imported by Company to X does not contain or relate to, any data pertaining to any user(s) or data subject(s) who has or have exercised an option to opt-out of receiving interest-based advertising.

**4.2 Personal Data.** Company represents and warrants that Company will not, and will not attempt to, connect or combine any X Materials either directly or indirectly with any Personal Data or to identifiers that are themselves directly or indirectly associated with any Personal Data. In addition, Company will put reasonable safeguards in place to prohibit X Materials from being linked to any Personal Data (whether directly or by inference).

**4.3 Privacy Compliance.** Company represents and warrants that (i) it will not provide X with Company Materials relating to sensitive information, including alleged or actual commission of a crime, health, negative financial status or condition, political affiliation or beliefs, racial or ethnic origin, religious or philosophical affiliation or beliefs, sex life, or trade union membership, or collected from websites, mobile applications, or other services where the product, message, or service that is being offered is prohibited by X’s Ads policies ([https://business.x.com/en/help/ads-policies](https://business.x.com/en/help/ads-policies)), and (ii) it will not (1) provide X with any Company Materials regarding children under the age of thirteen (13), or (2) send X any Company Materials or other data from a website, mobile application or online service directed to children, as defined in the Children’s Online Privacy Protection Act, currently at 16 CFR 312. Company acknowledges and agrees that it will at all times comply with the terms of the X Data Processing Addendum located at [https://privacy.x.com/en/for-our-partners/global-dpa](https://privacy.x.com/en/for-our-partners/global-dpa).

**4.4 Third Party Data.** Company represents and warrants that, in the event Company is obtaining data about users indirectly from one or more third parties (including, without limitation, data partners and/or advertisers, including, without limitation, Clients) to support Company’s performance obligations vis-à-vis X under this Agreement, it has contractually bound each such third party to the requirements contained in this Agreement including, without limitation, in this Section 4.

### 5. Ownership; License; Limitations and Restrictions.

**5.1 Ownership.** As between Company and X, Company retains all worldwide right, title and interest in and to the Company Materials, Company Marks, and the Company Service, excluding any X Materials, X Marks and X Service (and any derivative works or enhancements of any of the foregoing) incorporated therein, including but not limited to all intellectual property rights therein. Any rights not expressly granted herein are withheld. As between Company and X, X owns all worldwide right, title and interest in and to the X Materials, X Marks, and X Service and all future improvements, developments, enhancements, derivative works, and related rights based upon, related to, arising from, or associated with the (i) X Materials, (ii) the X Marks, and (iii) the X Service, including where such improvements, developments, enhancements or derivative works are created by using or referencing data, insights, information, or learnings derived from any Company Materials in accordance to the terms of this Agreement, or data related to the Company advertising activity on the X Service), including but not limited to all intellectual property rights therein.

**5.2 License to Company.** During the Term (including, any Wind-Down Period), to the extent that Company uses, or has access to, the Ad Products (or any aspect thereof), X hereby grants to Company a limited, royalty-free, non-exclusive, non-sublicensable, non-transferrable right and license to use and maintain any X Materials and X Marks that X may provide to Company under this Agreement solely if and as necessary to use the Ads Products (or any Individual Product) which X provides or makes accessible to Company, and to exercise its rights and fulfill its obligations under this Agreement, in each instance in accordance with the terms of this Agreement (including without limitation the restrictions and/or limitations on the use of X Materials). Company agrees that its use of the X Marks will at all times comply with the X Trademark Guidelines (defined below in Section 6).

**5.3 License to X.** During the Term (including, any Wind-Down Period), if Company uses, or has access to, the Ad Products (or any aspect thereof), Company grants to X a royalty-free, non-exclusive, sublicensable, non-transferable right and license to use, copy, display, maintain, transfer, modify, duplicate, and transmit the Company Materials and the Company Marks as necessary to fulfill Company instructions (including without limitation via the purchase and/or placement of ads on any ad inventory accessible on the X Network), to operate the Ad Products (or any Individual Product), and to exercise its rights and fulfill its obligations under this Agreement, in each instance in accordance with the terms of this Agreement.

**5.4 Limitations and Restrictions.**

5.4.1 X Materials are being provided to Company, and Company Materials are being provided to X, solely for the use of and/or provision of the Ads Products and for any other purpose expressly permitted under this Agreement.

5.4.2 Except as expressly permitted under this Agreement or unless otherwise mutually agreed in writing in advance by X and Company, Company shall not, nor allow any other party (including Clients) to, exploit, duplicate, copy, modify, derive, and/or re-use any X Materials, or any information, data, or insights derived from X Materials for any internal or external purpose (including, but not limited to, ad targeting, ad optimization, remarketing, behavioral targeting, retargeting, redirecting, or creating or augmenting in any manner groupings of users or devices segments, or creating or appending end user profiles, including those associated with any mobile device identifier or other unique identifier connected to any end user, computer, browser or device, or redirecting a user with advertising via advertising networks or exchanges, data brokers or any other advertising or monetization services). Further, Company will not use X Materials for identifying or re-identifying users in any way whatsoever (including by combining X Materials or data derived therefrom with data derived from third party sources).

5.4.3 Company may not, nor allow any other party (including Clients) to, incorporate any X Materials (including, without limitation, computer code, pixels, tags, or any other digital products provided by X to Company) into another product or service (except as necessary for the performance of this Agreement and permitted by the terms and conditions of this Agreement), translate, modify, reverse engineer or reverse compile, disassemble, make derivative works of, or otherwise attempt to discover any source code, underlying ideas, or algorithms of any X Materials without X’s express written permission.

5.4.4 Company will not, nor allow any other party (including Clients) to, interfere with, modify, disrupt or disable features or functionality of any X Materials, including without limitation any mechanism used to restrict or control the functionality, or defeat, avoid, bypass, remove, deactivate or otherwise circumvent any software protection or monitoring mechanisms of the X Materials.

5.4.5 Company will not, nor allow any other party (including Clients) to, 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 X Materials to any third party except as expressly permitted herein.

5.4.6 Company will not, nor allow any other party (including Clients) to, remove or alter any proprietary notices or marks in or on the X Materials.

5.4.7 Company will not, nor allow any other party (including Clients) to, provide use of the X Materials on a service bureau, rental or managed services basis or permit other individuals or entities to create links to the X Materials or "frame" or "mirror" the X Materials on any other server, or wireless or Internet-based device, or if applicable, otherwise make available to a third party, any token, key, password or other login credentials to the X Materials.

5.4.8 Company will not, nor allow any other party (including Clients) to, use the X Materials for any illegal, unauthorized or other improper purposes.

5.4.9 Company may not, nor allow any other party (including Clients) to, share the X Materials (including, without limitation, Data) with any third party (whether verbally or in writing), including any of Company’s clients or business partners or any Company personnel unrelated to the Ads Products, except if and as explicitly outlined herein, or as permitted by X in advance in writing (email accepted).

5.4.10 Company may not, nor allow any other party (including Clients) to, co-mingle or otherwise create any combined display of X Materials with Company Materials, data, content or other materials received from X under a separate agreement, or any other third-party materials or across advertising campaigns, except if and as expressly detailed herein or as approved by X in writing in advance.

5.4.11 Company may not, nor allow any other party (including Clients) to, offer or provide the Company Service and/or the X Materials as part of an advertising network and may not enable any programmatic export or otherwise enable machine consumption of X Materials by or to any third party (including, without limitation, Clients) without X’s prior written consent.

5.4.12 Company may not, nor allow any other party (including Clients) to, encourage or require users to engage with any Ads Products in such a fashion that may be misleading or deceptive to the user accessing the X Network, which may include methods such as offering incentives, points, rewards, cash, prizes, or anything else of monetary value, or any other methods that are malicious or fraudulent.

### 6. Incorporated Terms.

Company’s access to any given Individual Product and/or the associated X Materials is conditioned upon Company’s acceptance of, and compliance with, the following policies (collectively, the "**X Policies**"), each solely to the extent applicable to the Individual Product and X Materials that Company is accessing and/or using:

**6.1** Privacy Policy ([https://x.com/privacy](https://x.com/privacy))

**6.2** Terms of Service ([https://x.com/tos](https://x.com/tos))

**6.3** Applicable X Master Services Agreement ([https://legal.x.com/ads-terms/us.html](https://legal.x.com/ads-terms/us.html)) ([https://legal.x.com/ads-terms/international.html](https://legal.x.com/ads-terms/international.html)) or other such X Master Services Agreement referenced on an insertion order.

**6.4** Ads Policy Guidelines ([https://business.x.com/en/help/ads-policies](https://business.x.com/en/help/ads-policies)), including the Policies for Conversion Tracking and Custom Audiences ([https://business.x.com/en/help/ads-policies/campaign-considerations/policies-for-conversion-tracking-and-custom-audiences](https://business.x.com/en/help/ads-policies/campaign-considerations/policies-for-conversion-tracking-and-custom-audiences))

**6.5** Developer Agreement and Policy ([https://docs.x.com/developer-terms/agreement](/developer-terms/agreement))

**6.6** X Trademark and Brand Guidelines ([https://about.x.com/who-we-are/brand-toolkit](https://about.x.com/who-we-are/brand-toolkit))

Company agrees to the X Policies to the extent that Company accesses or uses Individual Products to which the individual policies apply. Company accepts and agrees that the X Policies may be modified by X from time to time in X’s sole discretion. In the event of a material modification to the X Policies that impacts Company, X will provide Company notice (such as by email or as may be posted on the X Service) of any such change. Company’s continued access or use of the X Materials and X Marks following any such updates or modifications will constitute binding acceptance of the updates and modifications.

### 7. Term; Termination Rights; Suspension Rights.

**7.1 Term.** This Agreement will commence on the Effective Date and will remain in effect for one (1) year (the “**Initial Term**”) and automatically continue thereafter for additional, successive one (1) year terms (each a “**Renewal Term**”), unless either party provides written notice of non-renewal at least thirty (30) days prior to the expiration of the Initial Term or terminates this Agreement in accordance with Section 7.2 below. The Initial Term and all Renewal Terms will collectively constitute the (“**Term**”).

**7.2 Termination; Suspension.** Upon completion of the Initial Term and the commencement of a Renewal Term, either party may terminate this Agreement for convenience upon provision of thirty (30) days’ prior notice to the other party. X may immediately terminate this Agreement upon written notice to Company if Company: (a) merges or is acquired, in whole or in part, by any third party, whether voluntarily or involuntarily, and/or by operation of law (including, without limitation, in connection with a merger, acquisition, or sale of assets, whether Company is the surviving or disappearing entity); or (b) has a receiver or similar party appointed for its property, becomes insolvent, acknowledges its insolvency in any manner, ceases to do business, makes an assignment for the benefit of its creditors, or files a petition in bankruptcy. Without limiting any other remedy in this Agreement or available at law or in equity, X may immediately suspend Company’s access to, or use of, the Ads Products, any given Individual Product, and/or the X Materials (or any part thereof) or terminate any and all license(s) granted to Company under this Agreement or this Agreement in its entirety, at any time and without notice, if X, in its sole discretion, believes or determines that: (i) Company is in violation of any of the Our Policies, or has breached or attempts to breach or is in non-compliance with any term or condition of this Agreement, and/or (ii) Company’s continued access to the Ads Products, a given Individual Product, and/or the X Materials will or may cause liability for X and/or X’s Clients or otherwise harm X or X’s Client’s service, business, or reputation.

**7.3 Effect of Termination.** Upon expiration or termination of this Agreement: (a) all rights and licenses granted hereunder will immediately cease and Company shall immediately cease accessing and using the X Materials; (b) within thirty (30) days of such expiration or termination, Company will remove, delete and securely erase all X Materials (including all copies and portions thereof) in all forms and types of media from the Company Service or otherwise in Company’s possession or control; and (c) within thirty (30) days of such expiration or termination, Company will delete and securely erase all copies of any Confidential Information (as defined below in Section 9) in Company’s possession or control. X will not be liable for any costs, expenses, or damages as a result of its termination of this Agreement.

**7.4 Wind Down Period.** Notwithstanding the foregoing, in the event that either party terminates this Agreement pursuant to this Section 7, the terms and conditions of this Agreement, and the respective rights and obligations of the parties hereto, shall, at X’s sole election (and upon X’s written notification to Company of such election), continue to apply during a Wind-Down Period (as defined below) solely with respect to any and all Client advertising campaigns that are then ongoing at the time of such termination (which shall include, without limitation, circumstances in which X and/or the applicable Client have elected to run an advertising campaign, even if such advertising campaign has not actually commenced at the time of termination). As used herein, “**Wind-Down Period**” shall mean a period commencing upon the termination of the Term and continuing until the earlier of: (i) ninety (90) days following such termination date; or (ii) the completion of all Client advertising campaigns that were then ongoing (as described above) as of such termination date.

**7.5 Survival.** Those terms that by their nature should survive either expiration or termination of this Agreement, shall survive, including, but not limited to, Sections 3-15.

### 8. Security; Security Breaches; Regulatory Notice; Data Deletion; Audit.

**8.1 Security.** Company will use industry-standard security measures in connection with its performance under this Agreement, including, but not limited to, administrative, technical, and physical security measures for data transmission and storage at least as restrictive as industry-standard security measures for the transmission and storage of the types of data included in the X Materials. Company will also use reasonable technical and organizational security measures (including, at a minimum, password protection and access protocol restrictions), and in no event less care than it uses in connection with transmitting and securing Company’s own data of the same or similar nature, to restrict access to X Materials and Confidential Information to only those individual Company personnel who need to access such X Materials in order to exercise Company’s rights and/or fulfill Company’s obligations pursuant to this Agreement.

**8.2 Security Breaches.** Company shall notify X in writing (which may include email) within twenty-four (24) hours of becoming aware of any security breach or other improper access that resulted, may have resulted, or had the potential to result, in exposure of any X Materials and/or data related to, based upon, or arising from, this Agreement. Company will consult and cooperate with X in any investigations, provide any required notices and/or provide any information reasonably requested by X.

**8.3 Regulatory Inquiries.** Company shall notify X in writing (which may include email) within twenty-four (24) hours of Company’s receipt of notice of any inquiry from a government or regulatory agency concerning a security breach (or similar incident), Company’s alleged misuse of consumer data, or any other aspect of Company’s operations that are reasonably related, either directly or indirectly, to this Agreement.

**8.4 Data Deletion.** Company shall delete and securely erase any and all X Materials from its systems when Company no longer has a legitimate business need to retain such X Materials in order to exercise Company’s rights and/or fulfill Company’s obligations under this Agreement (including, without limitation, in the event that the applicable Client ceases to use the Ads Products or otherwise ceases to use the Company Services), but in no event later than the earlier of: (a) ninety (90) days from the date that Company first receives the applicable Data, or (b) thirty (30) days following the expiration or termination date of the Agreement. In addition, at any time, Company agrees to delete and securely erase, immediately upon X’s written request (which may be delivered via email), any X Materials that X deems necessary or desirable to delete and securely erase (in X’s sole and absolute discretion).

**8.5 Audit.** Upon reasonable prior written notice (of no less than ten (10) days), no more than twice each calendar year during the Term and once during the six (6) month period after the date that this Agreement terminates or expires, at X’s expense, X shall be provided access to Company facilities to audit the processes, methodologies, practices and systems used by Company in performance of its obligations and exercising its rights under this Agreement. For clarity, Company acknowledges and agrees that (i) X may engage a third-party auditor to perform any such audit on its behalf; and (ii) notwithstanding anything to the contrary herein, X may share any relevant Confidential Information concerning Company (including, without limitation, the terms and conditions of this Agreement) with such third-party auditor solely as required to facilitate any such audit.

### 9. Confidential Information.

Each party agrees that all business, technical and financial information that is designated as “confidential” or “proprietary,” or that is disclosed in a manner that a reasonable person would understand the confidential nature of the information being disclosed by the disclosing party (“**Confidential Information**”). For clarity, all proprietary information provided by X to Company pursuant to this Agreement, which includes, without limitation, information (tangible or intangible) regarding X’s technology, designs, techniques, research, know-how, specifications, product plans, pricing, customer information, user data, current or future strategic information, current or future business plans, policies or practices, employee information, and other business and technical information (including, without limitation, results, analysis or data regarding uptime, reliability, traffic and growth metrics, network quality, and other usage statistics of the X Service, in the aggregate or otherwise, derived from Company’s use of the X Materials or the X Service and/or access to technical documentation, developer newsletters and/or online portals or forums) is X Confidential Information and proprietary to X. Without limiting the foregoing, the terms and conditions of this Agreement, the X Materials, any product requirements, and any other documentation, onboarding processes or other materials provided by X to Company under this Agreement shall be deemed X Confidential Information. Except as expressly allowed herein, the receiving party will hold in confidence and not use or disclose (except in connection with the performance of such party’s obligations under this Agreement) any Confidential Information of the disclosing party. The receiving party shall not be obligated under this Section with respect to information that the receiving party can document through writing or testimony that such information: (i) is or has become readily publicly available through no fault of the receiving party or its employees or agents; (ii) is received from a third party lawfully in possession of such information, and the receiving party has no knowledge of any disclosure restrictions on such third party to disclose such information; (iii) is disclosed to a third party by the disclosing party without restriction on disclosure; (iv) was rightfully in the possession of the receiving party without restriction prior to its disclosure by the other party; or (v) was independently developed by employees or consultants of the receiving party without reliance on such information. The receiving party may make disclosures required by law or court order, provided that the receiving party notifies the disclosing party of the issuance of such order and allows the disclosing party to participate in the proceeding.

### 10. Representations and Warranties.

Company represents and warrants that: (i) it has all requisite legal and corporate power to enter into this Agreement; (ii) it has taken all action required to make this Agreement a legal, valid and binding obligation; (iii) it has no agreement or understanding with any third party that interferes with or will interfere with its performance of its obligations under this Agreement; (iv) it has obtained and shall maintain all permissions, consents, rights, approvals and licenses necessary to perform its obligations and grant all rights and licenses granted under this Agreement including, without limitation, all rights necessary for Company to grant X a license to use Company Materials to place ads on any advertising inventory available or accessible to X on the X Service or otherwise and provide the Company Service; (v) the Company Service and Company Materials do not, and will not, infringe, misappropriate or otherwise violate any third party rights; and (vi) its business and performance under this Agreement, including its provision of the Company Service, is and shall be in compliance with all applicable foreign, federal, state and local laws and government rules and regulations. Company further represents and warrants that: (a) it has no knowledge of any actual, pending, or threatened claims, lawsuits, actions, or charges pertaining to the Company Service, any Company Materials or other deliverables related to this Agreement or Company’s practices regarding data security, data use, or privacy; and (b) in the event that Company is accessing or using the Ads Products (or any aspect thereof) on behalf of a Client, Company has the authority as agent to such third party to use such Company Materials on such third party’s behalf, to convey the rights to such third party materials as may be provided to X in the Company Materials, and to bind such third party to the terms of this Agreement.

### 11. Feedback. Beta Services.

If and to the extent that X provides (in its sole and absolute discretion) Company with any access to any features and functionality that are designated private, unreleased, in development, or in “alpha” or “beta” (collectively, “**Beta Services**”), Company acknowledges and agrees that Beta Services are not supported by X, and Beta Services (or any portion thereof) may be launched publicly or made unavailable at any time (in each case, in X’s sole and absolute discretion). Beta Services are provided “AS IS” to the fullest extent of the law, and Company’s use of such Beta Services is at Company’s own risk and consent. All Beta Services will be considered X Confidential Information. Company agrees that participation in any Beta Service will assist X in research, analyzing and validating some existing and/or prospective programs, products and/or tools, and that if Company provides X with any comments, feedback or other information to assist X in evaluating and improving such programs, products and/or tools (“**Feedback**”), X and its designees will be free to copy, modify, create derivative works, publicly display, disclose, distribute, license and sublicense, incorporate, and otherwise use the Feedback, including derivative works thereto, for any and all commercial and non-commercial purposes with no obligation or compensation of any kind to Company or any third party. For clarification, Feedback does not include and X will not use Company’s name or publicly disclose Company’s Beta Services performance results. Feedback will also include any Company comments concerning the X Materials, the Ads Products, and/or Company’s evaluation and use thereof. Company agrees that nothing in this Agreement will prevent X from developing products or services that may be competitive with Company’s or any Clients’ or End Users’ products or services.

### 12. Warranty Disclaimer.

THE X MATERIALS, THE ADS PRODUCTS, AND ANY OTHER X PRODUCTS AND SERVICES (INCLUDING, WITHOUT LIMITATION, ANY BETA SERVICES) AND ANY X MARKS PROVIDED HEREUNDER ARE PROVIDED “AS IS” AND ON AN “AS AVAILABLE” BASIS, WITHOUT WARRANTY OF ANY KIND. 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 COURSE OF DEALING OR USAGE OF TRADE. X DOES NOT WARRANT THAT THE X MATERIALS, THE ADS PRODUCTS, AND ANY OTHER X PRODUCTS AND SERVICES (INCLUDING, WITHOUT LIMITATION, ANY BETA SERVICES) OR ANY X MARKS PROVIDED HEREUNDER WILL MEET COMPANY’S REQUIREMENTS OR THAT USE OF SUCH X MATERIALS, OTHER X PRODUCTS AND SERVICES AND/OR ANY X MARKS WILL BE ERROR-FREE, UNINTERRUPTED, VIRUS-FREE, OR SECURE. THIS DISCLAIMER OF WARRANTY MAY NOT BE VALID IN SOME JURISDICTIONS, AND COMPANY MAY HAVE WARRANTY RIGHTS UNDER LAW WHICH MAY NOT BE WAIVED OR DISCLAIMED. ANY SUCH WARRANTY EXTENDS ONLY FOR THIRTY (30) DAYS FROM THE EFFECTIVE DATE OF THIS AGREEMENT (UNLESS SUCH LAW PROVIDES OTHERWISE).

### 13. Indemnification.

Company will defend, at its own expense, any claim, suit or action against X brought by a third party to the extent that such claim, suit or action is based upon an allegation that (i) the Company Materials, the Company Service, the Company Marks, X’s use of the Company Materials or Company Marks, or the technology used to generate the Company Materials and/or the Company Service infringes any rights of any third party (including, without limitation, any intellectual property rights, privacy rights or publicity rights); (ii) Company has breached any of its obligations, representations or warranties hereunder, including Company’s data security, data use, and privacy obligations or (iii) Company’s unauthorized use of the X Materials and/or X Marks in violation of the terms, conditions and restrictions set forth in the Agreement. Company will indemnify and hold X harmless from and against any losses, damages, liabilities, penalties, costs and expenses attributable to any such claim. Company is responsible for defending any claim against X, subject to X’s right to participate with counsel of its own choosing, and for payment of all judgments, settlements, damages, losses, liabilities, costs, and expenses, including reasonable attorney’s fees, resulting from all claims against X, provided that Company will not agree to any settlement related to any claims without X’s prior express written consent regardless of whether or not such settlement releases X from any obligation or liability. X will give Company prompt notice of an indemnification obligation (provided that failure to do so will only relieve Company of its obligation to the extent it can demonstrate material prejudice from the failure).

### 14. Limitation of Liability.

IN NO EVENT WILL X BE LIABLE TO COMPANY OR ANY CLIENTS OR END USERS FOR ANY SPECIAL, INCIDENTAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR FOR LOST REVENUE, LOST PROFITS, COSTS OF REPLACEMENT OF GOODS OR SERVICES, LOSS OF TECHNOLOGY, GOODWILL, RIGHTS OF SERVICES, LOSS OF DATA OR INTERRUPTION OR OF LOSS OF USE OF SERVICE ARISING OUT OF OR IN CONNECTION WITH THIS AGREEMENT, OR FOR COMPANY’S OR CLIENT’S OR END USER’S USE OF THE X MATERIALS, X MARKS OR ANY X PRODUCTS AND/OR SERVICES (INCLUDING, WITHOUT LIMITATION, THE ADS PRODUCTS) PROVIDED HEREUNDER, WHETHER SUCH LIABILITY ARISES FROM ANY CLAIM BASED UPON CONTRACT, WARRANTY, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, OR OTHERWISE, AND WHETHER OR NOT X HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. INSOFAR AS APPLICABLE LAW PROHIBITS ANY LIMITATION ON LIABILITY HEREIN, THE PARTIES AGREE THAT SUCH LIMITATION WILL BE AUTOMATICALLY MODIFIED, BUT ONLY TO THE EXTENT SO AS TO MAKE THE LIMITATION COMPLIANT WITH APPLICABLE LAW. THE PARTIES AGREE THAT THE LIMITATIONS ON LIABILITIES SET FORTH HEREIN ARE AGREED ALLOCATIONS OF RISK AND WILL APPLY NOTWITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY. IN ANY CASE, X’S AGGREGATE LIABILITY UNDER THIS AGREEMENT WILL NOT EXCEED FIFTY U.S. DOLLARS (U.S. \$50).

### 15. Miscellaneous.

**15.1 Publicity.** Company may not issue any press release, blog post or otherwise make any public announcement or disclosure concerning this Agreement, any of the activities contemplated hereunder, or concerning the relationship between Company and X without X’s prior written consent (which may be provided by email).

**15.2 User Protection.** Company will not (a) knowingly allow or assist any government entities, law enforcement, or other organizations to conduct surveillance on the X Service or the X Materials or obtain information on X’s users or their posts that would require a subpoena, court order, or other valid legal process, or that would otherwise have the potential to be inconsistent with X’s users’ reasonable expectations of privacy; or (b) display, distribute or otherwise make available X Materials to any person or entity that Company reasonably believes will use such data to violate the Universal Declaration of Human Rights (located at [https://www.un.org/en/universal-declaration-human-rights/index.html](http://www.un.org/en/universal-declaration-human-rights/index.html)), including without limitation Articles 12, 18, or 19. Any law enforcement personnel seeking information about X users will be referred 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).

**15.3 Government Use.** The X Materials may be “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 Materials 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. Contractor/manufacturer is X Corp., 865 FM 1209, Building 2, Bastrop, TX 78602, USA.

**15.4 Compliance with Laws; Export/Import.** Each party will comply with all applicable foreign, federal, state, and local laws, rules and regulations. Company shall not export or re-export X Services or X Data in violation of the Our Policies (as defined herein) or applicable law. The X Materials may be subject to U.S. export laws and may be subject to import and use laws of the country where it is delivered or used. Company agrees to abide by these laws. Under these laws, the X Materials 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; or 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.

**15.5 Modifications.** X may update or modify the Our Policies, Analytics Data Display Requirements (attached as [Exhibit A-2](#Exhibit-A-2)), the “X Marketing Partner” program-related terms and conditions (attached as [Exhibit C](#Exhibit-C)) and any other technical documentation and any other guidelines or policies related to the X Materials from time to time, at X’s sole discretion, by posting the changes, as applicable, on X’s developer site, located at: [https://developer.x.com](https://developer.x.com) (as may be amended from time to time), the URL where the applicable X Policy is posted or by otherwise notifying Company (such notice may be via email). If any change is unacceptable to Company, Company’s only recourse is to cease all use of the X Materials and X Marks.

**15.6 Notices.** Except as otherwise stated in Sections 6 and 15.5, any notice required or permitted by this Agreement shall be in writing and shall be delivered as follows, with notice deemed given as indicated: (a) by personal delivery when delivered personally; (b) by overnight courier upon written verification of receipt; (c) by certified or registered mail, return receipt requested, upon verification of receipt; or (d) by electronic mail when the recipient acknowledges having received the applicable email. Notice shall be sent to the addresses set forth below or such other address as either party may specify in writing. Notices for breach sent by Company to X must be sent via overnight courier or certified or registered mail only. Notices to Company will be sent to the Company address on record with X. Notices to X Corp. will be delivered to: X Corp., 865 FM 1209, Building 2, Bastrop, TX 78602, USA, Attn: Legal Department, with a compulsory copy to: Head of Ads API and [legalnotices@x.com](mailto:legalnotices@x.com). Notices to X Internet Unlimited Company will be delivered to: Legal Department, X Internet Unlimited Company, One Cumberland Place, Fenian Street, Dublin 2, D02 AX07, Ireland.

**15.7 Assignment.** Company may not assign this Agreement or any of the rights or obligations granted hereunder, in whole or in part, to any third party, whether voluntarily, involuntarily and/or by operation of law (including, without limitation, in connection with a merger, acquisition, or sale of assets, whether Company is the surviving or disappearing entity), except with the express written consent of X, and any attempted assignment in violation of this paragraph is null and void, and X may immediately terminate this Agreement. This Agreement will bind and inure to the benefit of each party’s permitted successors and assigns.

**15.8 No Subcontractors.** Company may not use a third party to perform or fulfill any of Company’s obligations or duties under this Agreement, unless approved in advance by X in writing, which approval may be provided by email.

**15.9 No Partnership.** This Agreement does not create or imply any partnership, agency or joint venture. No waiver by either party of any covenant or right under this Agreement will be effective unless memorialized in a writing duly authorized by such party.

**15.10 No Third-Party Beneficiaries.** There shall be no third-party beneficiaries to this Agreement.

**15.11 Severability.** If any part of this Agreement is determined to be invalid or unenforceable by a court of competent jurisdiction, that provision will be enforced to the maximum extent permissible and the remaining provisions of this Agreement will remain in full force and effect.

**15.12 Waiver.** The waiver by either party of a breach of any provision of this Agreement by the other party shall not operate or be construed as a waiver of any other or subsequent breach by that party. No waiver by X of any covenant or right under this Agreement will be effective unless memorialized in a writing duly authorized by X.

**15.13 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.

**15.14 Governing Law and Jurisdiction.** If X Corp. is the contracting entity hereunder, the terms of the Agreement and any dispute relating thereto or between Company and X will be governed by the laws of the State of Texas, without regard to conflict/choice of law principles. The United Nations Convention on Contracts for the International Sale of Goods does not apply to the Agreement. If a dispute, claim or controversy arising out of or relating to this Agreement or the breach, termination, enforcement, interpretation or validity thereof, including the determination of the scope or applicability of this agreement to arbitrate arises, Company agrees to provide X with notice of the dispute, and to provide a ten (10) business day resolution period in which X and Company may attempt to work out the dispute informally. If, after the ten (10) business day resolution period, X and Company cannot resolve the dispute, Company agrees to bring any dispute or claim arising out of this Agreement 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 we have 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 acting 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).

If X Internet Unlimited Company is the contracting entity hereunder, the terms of the Agreement and any dispute relating thereto or between Company and X will be governed by the laws of Ireland, without regard to conflict/choice of law principles. The parties agree that neither the United Nations Convention on Contracts for the International Sale of Goods, nor the Uniform Computer Information Transaction Act (UCITA) shall apply to this Agreement, regardless of the states in which the parties do business or are incorporated. Any dispute, claim or controversy arising out of or relating to this Agreement or the breach, termination, enforcement, interpretation or validity thereof 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 you and us 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 we have against you in any competent court in the country in which you reside that has jurisdiction and venue over the claim.

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

**15.15 Injunctive Relief.** Each party agrees that money damages would be an inadequate remedy in the event of a breach or threatened breach of the provisions in this Agreement protecting X’s intellectual property (including, without limitation, the X Materials) and/or X’s Confidential Information, and that, in the event of such a breach or threat, X, in addition to any other remedies to which X is entitled, is entitled to such preliminary or injunctive relief (including an order prohibiting the other party from taking actions in breach of such provisions), without the need for posting bond, and specific performance as may be appropriate to preserve all of X’s rights.

**15.16 Updates.** X may update the terms of this Agreement and any policies referenced herein from time-to-time, at its sole discretion, and will provide email notice to Company or posting notice to the URL identified below. Such notice will indicate the effective date of any such updates. The terms of this Agreement will be available for Company to view at any time at [https://docs.x.com/developer-terms/ads-api-agreement](/developer-terms/ads-api-agreement). Company’s continued use of any Individual Product(s) after the effective date provided in the applicable notice will indicate Company’s acceptance of such updates.

**15.17 Entire Agreement.** This Agreement (including the Exhibits attached hereto) constitutes the entire agreement between the parties relating to this subject matter hereof and supersedes and replaces all prior or contemporaneous proposals, understandings, communications and agreements, oral or written, concerning such subject matter. Any amendments to this Agreement shall be made in writing and signed by a representative of the respective parties authorized to bind the parties.

## Exhibit A: Individual Product Terms/X Ads API

Capitalized terms not defined in these Individual Product Terms have the meaning set forth in the main body of the Agreement. To the extent that Company participates in the “X Ads API Program,” the following terms and conditions of this Exhibit A (including Exhibit A-1 and Exhibit A-2) will apply:

### 1. X Ads API Introduction; Access.

**1.1 Introduction.** The X advertising application programming interface (API), and the accompanying documentation, code and related materials (collectively, the “**X Ads API**”) that provides Company with “read/write” access that allows Company to engage in Campaign Management of X Ads and/or with “read” access to certain reporting of Data about the performance of X Ads Campaigns.

**1.2 API Access.** X will (in its sole and absolute discretion) decide if and whether to grant Company “read” or “read/write” X Ads API access. X may implement a review process for granting X Ads API access, but is not required to do so.

### 2. Ads API License.

On condition that X decides to provide Company X Ads API access, and subject to Company’s continuing compliance with terms and conditions of the Agreement, X grants Company a limited, non-exclusive, non-transferable, non-sublicensable, revocable license during the Term to: (a) use the X Ads API to implement the Company Service for the purpose of providing a Client’s End Users with access to Data related to such Client’s X Ads Campaigns (and, if Company has “read/write” API access, to enable Campaign Management of X Ads through the Company Service); (b) display the Data in aggregated format solely within the Company Service in accordance with the Analytics Data Display Requirements (defined below in Section 3 of this Exhibit A) to a Client’s End Users solely for the purpose of optimizing such Client’s X Ads Campaigns; (c) modify the Data only as necessary to format it for, and display it, within the Company Service; (d) enable the Company Service to export Data only in a format that X has approved in writing and that complies with the Analytics Data Display Requirements and via an export mechanism that is approved by X in writing; and (e) use and display the X Marks that X makes available for use in connection with the X Ads API and/or Data solely to attribute X as the source of the Data or as otherwise expressly permitted under the Agreement (in each instance, in accordance with the X Trademark Guidelines).

### 3. Display Requirements, Integration and Other Requirements.

Company’s implementation and use of the X Ads API and Data must at all times comply with: (a) the product requirements attached hereto as Exhibit A-1 (“**Product Requirements**”); (b) the display requirements attached hereto as Exhibit A-2 (“**Analytics Data Display Requirements**”); (c) all technical documentation for the X Ads API that has been, or will be, provided to Company by X (including, without limitation, any endpoint specifications or requirements); (d) any onboarding processes specified by X related to the X Ads API and Data; (e) the Our Policies; and (f) any other guidelines and policies applicable to the X Ads API and Data that may be provided to Company by X.

### 4. Compliance.

Company will abide by all instructions provided or communicated to Company by X, including, without limitation, the limitations on access, calls and use of the X Ads API and any additional limitations or restrictions related to tokens, rate limits, keys, passwords or other login credentials to the X Ads API. Any such instructions are determined by X in its sole and absolute discretion. Company shall comply with any X request to inspect and access the Company Service, including, without limitation, providing X with any Company Service code related to the implementation of the X Ads API, to ensure that the integration of the X Ads API into, and display of the Data within, the Company Service complies with the Product Requirements and Analytics Data Display Requirements, X quality controls and/or other terms and conditions of this Agreement. X may monitor Company’s use of the X Ads API to improve the X Services.

### 5. Control of Allocation of X Ads Inventory.

For clarity, and without limiting the generality of any other term or condition of this Agreement, nothing in this Agreement is meant to represent or imply that Company or the Company Service will have access, via the X Ads API, to any particular inventory or category of X Ads, and X may (in its sole and absolute discretion) elect from time to time, to limit, without restriction, the allocation of X Ads inventory to which Company or the Company Service has access (e.g., without limitation, due to X’s strategic decisions concerning sales channels, direct vs. non-direct client relationships, agency relationships, etc.).

### 6. Control of X Ads Features, API Calls and Functionality.

For clarity, and without limiting the generality of any other term or condition of this Agreement, nothing in this Agreement is meant to represent or imply that Company or the Company Service will have access, via the X Ads API, to any particular X Ads feature, API call or functionality, and X may (in its sole and absolute discretion) elect from time to time, to limit, without restriction, those X Ads features, API calls and/or functionalities to which Company or the Company Service has access (for any or no reason).

### 7. Geography Data.

Company will not (and will not allow others to) use or access the X Ads API to aggregate, cache or store place or other geographic location information contained in any Data or otherwise.

### 8. Removals.

When requested by X, through the X Ads API or otherwise, Company will promptly: (a) delete Data from the Company Service that X reports as deleted or expired; (b) change Company’s treatment of Data that X reports is subject to changed sharing options; and (c) modify Data on the Company Service that X reports has been modified. Company is responsible for the quality of X Ads transmitted to the X Service by the Company Service. X reserves the right to revoke access to the X Ads API and/or, if applicable, remove any specific X Ads from the X Service for any objectionable use by Company or Clients.

### 9. Updates.

Company acknowledges that X may update or modify the X Ads API, from time to time, and in X’s sole and absolute discretion (in each instance, an “**Update**”). Unless otherwise mutually agreed by X and Company in advance in writing (email to suffice), Company is required to implement and use the most current version of the X Ads API and to make any changes to the Company Service, at Company’s sole cost and expense, that are required as a result of such Update no later than thirty (30) days from the date that X notifies Company of the Update. Company will implement all tools (if any) provided by X to enable Updates, as applicable. Updates may adversely affect the manner in which the Company Service accesses or communicates with the X Ads API or displays Data. Company’s continued access or use of the X Ads API following any such Update will constitute binding acceptance of the Update.

### 10. Support.

Company is responsible for providing all support and technical assistance to Clients and their End Users regarding the use of the Company Service (including any issues related to any Ads Product). X is not obligated to provide support or technical assistance directly to Company or any Clients or any of their End Users, and Company will not represent to any Clients or any of their End Users that X is available to provide such support.

## Exhibit A-1: Product Requirements

The Company Service should enable marketers to more efficiently optimize X Ads campaigns, take advantage of X’s real-time conversation, and develop X Ads that improve the user experience.

Accordingly, the Company Service, at all times, will meet the following requirements:

### 1. Product Pricing. No Monetization.

Paid access to the Company Service must be priced on a fixed or variable percentage of spend fee structure. Company will not charge Clients a premium for access to X Ads and/or Data through the Company Service in excess of Company’s standard rates for the Company Service.

### 2. Transparency.

**2.1 Spend.**

2.1.1 Any pricing reports delivered by Company to Clients and their End Users must clearly state and itemize (i) the X Ads spend in X’s native metrics (e.g., as applicable, CPE/CPF) and (ii) the fees charged for use of the Company Service. In addition, Company must always include CPE or CPF metrics (or other applicable X native metrics) adjacent to last-click attribution metrics (e.g., CPC) or other reporting metrics (e.g. CPM).

2.1.2 Company Service will include a self-serve reporting dashboard that will include the capability for Company to report on all metrics provided via the X Ads API.

**2.2 Data.** Company will: (i) use commercially reasonable efforts to maintain up-to-date Data within the Company Service in connection with the X Integration (defined below in Section 6.3 of this Exhibit A-1) in accordance with the then-current Analytics Data Display Requirements; and (ii) clearly disclose to Clients and their End Users any material delay inherent in any information regarding Client’s X Ads Campaigns and/or related analytics data.

### 3. Accounts.

Each End User must be given a separate account to access the Company Service, including a unique user name and password.

### 4. Company Service.

Each customized version of the Company Service for a specific Client (including, without limitation, a white-labeled version of Company Service for a specific Client) must be approved by X in advance and in writing (email to suffice for such purposes).

### 5. Clients and Account Management.

**5.1** A Client must be given the ability to quickly and easily disassociate its X Ads Campaigns from the Company Service and regain exclusive, direct control of its X Ads account(s).

**5.2** Only a Client and its End Users may be allowed to view such Client’s account data or features via the Company Service.

### 6. Other Requirements.

**6.1** Any Company Service functionality that replicates a X feature will utilize X’s naming nomenclature and feature names, subject to any applicable X Trademark Guidelines.

**6.2** Unless otherwise mutually agreed by the parties in advance and in writing, Company will not provide Clients and their End Users or any other third party with access to Data except for the aggregated derivations of such material embodied in the user interface of the Company Service.

**6.3** Company may not commercialize, market or provide access to any X Materials to any third parties (including any Clients or their End Users) until the implementation of the X Ads API and integration and display of any Data within Company Service (collectively, the “**X Integration**”) has been approved in advance by X via the process described in this Section. Company will give X access to the Company Service so that X can review the X Integration. X will inform Company in writing (email being sufficient) if the X Integration is approved or rejected (in X’s sole discretion). Throughout the Term, Company will submit to X any changes to the Company Service that affect the X Integration, which X shall have the right to approve or reject in writing (email being sufficient), in X’s sole discretion.

## Exhibit A-2: Analytics Data Display Requirements

These Analytics Data Display Requirements govern how Company can display Data within the Company Service. Company agrees to abide by these Analytics Data Display Requirements at all times.

### 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://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

**1.** The applicable defined metrics for a given Campaign Objective (as described above in the Defined Metrics section of this Exhibit A-2) must be shown every time a campaign is displayed within the Company Service.

**2.** If the Company Service displays any organic post analytics data, Company must comply with the X Developer Agreement & Policy located at: [https://docs.x.com/developer-terms/agreement](/developer-terms/agreement) as it relates to Company’s implementation, use and display of the organic post analytics data.

**3.** If the Company Service displays metrics about campaigns run on third party networks or by third party publishers (i.e., “cross-channel metrics”) side-by-side with Data, then the following requirements and restrictions apply:

**3.1** Any cross-channel metrics displayed alongside the Data in the Company Service can only include the same category of campaign objective metrics as the applicable X-defined Campaign Objective metrics for such campaign (as described above in the Defined Metrics section of this Exhibit A-2).

By way of example only - If an advertiser is running an app install campaign on a third-party network, only cross-channel metrics that are of the same category as the applicable X-defined metrics for the app install Campaign Objective can be shown alongside the Data.

**3.2** Aggregating data to display cross-channel metrics is not permitted unless the aggregated metrics can be referenced (across all third-party networks/publishers) against a category of metrics associated with a campaign objective that is the same to the applicable X-defined Campaign Objective metrics (as described above in the Defined Metrics section of this Exhibit A-2). By way of example only - Aggregating total engagements for network A, network B, and network C would not be permitted if engagement rates across all channels are not calculated using the same formulas.

**4.** If the Company Service displays any category of metrics sourced from third parties other than X (“**third-party-sourced metrics**”), then the following requirements and restrictions apply:

**4.1** The same requirements and restrictions that apply to displaying cross-channel metrics set forth above in Section 3 apply to the display of any third-party-sourced metrics.

**4.2.** Any third-party-sourced metrics that are displayed alongside Data for a campaign in the Company Service must be the same category of campaign objective metrics as the applicable X-defined Campaign Objective metrics for such campaign (as described above in the Defined Metrics section of this Exhibit A-2). By way of example only:

* If Company displays link click and click-rate metrics from a third-party source, Company will display X’s click and click-rate metrics alongside the third-party-sourced link click and click rate metrics.

* If Company or any of its Clients uses a third-party tracking solution to track website clicks from Promoted posts and such data is displayed in the Company Service, Company must show link clicks, click rate, cost per link click and CPA from X (if available) alongside such third-party-sourced data.

**4.3** Notwithstanding Section 4.2 of this Exhibit A-2, if the third-party-sourced metrics are from a third-party tracking solution provided by a X Conversion Tracking Partner (as defined below), then X requires that only the Data delivered through the X Ads API (and not any corresponding data delivered by the X Conversion Tracking Partner) is displayed in the Company Service, unless otherwise agreed by X in writing in advance (in each instance). For the avoidance of doubt, Company will not display any data sourced from a X Conversion Tracking Partner alongside, or in place of, any Data delivered through the X Ads API. As used in this Exhibit A-2, “**X Conversion Tracking Partner**” means an authorized X conversion tracking partner (as designated by X, in its sole and absolute discretion).

## Exhibit B: Individual Product Terms/Custom Audiences

Capitalized terms not defined in these Individual Product Terms have the meaning set forth in the main body of the Agreement. To the extent that Company uses or accesses the X Custom Audiences Program the following terms and conditions of this Exhibit B will apply:

### 1. Custom Audiences.

**1.1 Introduction.** The X Custom Audiences Program allows for the import and creation of specific segments of users (each a “**Custom Audience**”) for the targeting of advertising Campaigns on the X Service. The parties acknowledge that in order to utilize X Custom Audiences Program, Company, its Client, or a third party service provider approved by X (“**Data Partner**”) is required to provide X with a hashed set of users or devices (which may include email, cookies, device IDs, tracking pixels, etc.) in order for X to complete a match with X users and create Custom Audiences. The Custom Audiences created on behalf of a specific client(s) will be stored in each such Client’s X Ads account for use by Company or Client to target, or retarget, as applicable, advertising on the X Service.

**1.2 Data Usage and Opt-Out.** With respect to any data used in connection with the Custom Audiences Program, in addition to the obligations set out in the Data Protection Addendum found at [https://privacy.x.com/en/for-our-partners/global-dpa](https://privacy.x.com/en/for-our-partners/global-dpa), Company agrees and, if applicable, will ensure that its Data Partner(s) agree that (i) Company or such Data Partner (as applicable) have secured all necessary rights, consents, waivers, licenses for use of such data, and (ii) that Company or such Data Partner (as applicable) have provided any users from whom the data is collected with legally-sufficient notice that fully discloses the collection, use, and sharing of the data Company provides to X for purposes of serving ads targeting to users’ interests, and legally sufficient instructions on how users can opt out of X’s interest-based advertising through the methods described here ([https://help.x.com/safety-and-security/privacy-controls-for-tailored-ads](https://help.x.com/safety-and-security/privacy-controls-for-tailored-ads)). Data Company uses in connection with the Custom Audiences Program and/or to create a Custom Audience will not include any data from any user who has opted out of having his/her data used by Company, its Data Partner, or any third party on Company’s behalf. If Company receives a user opt-out after such user was included in an audience provided to X, Company must promptly, but no less frequently than once every twenty-four (24) hours, remove such user(s) from any Custom Audience in which such user was included. Company will provide the data in a format selected by X and acceptable to Data Partner (if/as applicable). In addition to the terms and conditions of this Agreement, Company’s use of X Custom Audiences program will be subject to the terms of the [X Master Services Agreement](https://legal.x.com/ads-terms.html) and Custom Audiences Program T\&Cs and applicable policies, including X’s Policies for Conversion Tracking and Custom Audiences, at [https://legal.x.com/ads-terms.html](https://legal.x.com/ads-terms.html) and [https://business.x.com/en/help/ads-policies/campaign-considerations/policies-for-conversion-tracking-and-custom-audiences](https://business.x.com/en/help/ads-policies/campaign-considerations/policies-for-conversion-tracking-and-custom-audiences).

**1.3 Additional Program Requirements.** Company’s access to, and use of, the X Custom Audience Program is additionally subject to its compliance with the technical instructions and program policies provided by X to Company (the “**Program Integration Spec**”). Company and X will mutually agree on a process for Company to import or upload Custom Audiences to X.

### 2. Shareable Audiences.

Notwithstanding anything to the contrary set forth in Section 1.1 hereinabove, as a service to Company, at Company’s request and in Company’s sole discretion, X may allow Company to “share” Custom Audiences created for Company amongst grouped X advertiser accounts and/or X @handles and/or otherwise with third parties on the X Service. As used herein, “sharing” an audience means that Company would instruct X to, without limitation, enable grouped X Advertiser Accounts and/or X @handles and/or third parties to access, use, and target advertising Campaigns against the “shared” Custom Audience. Company represents and warrants that it has all necessary rights and authority to share any such audience data in accordance with the instructions given to X by Company. If Company is providing the audience data, and/or managing the Custom Audiences on behalf of a third party (including, without limitation, a Client), Company represents and warrants that Company has the authority as agent for such party to use any such data on the third party’s behalf, to grant X the rights described herein, and to bind such third party to the terms of this Agreement. Notwithstanding the foregoing, nothing in this Section requires X to make the functionality that enables “sharing” Custom Audiences described herein (or any portion thereof) available at any time to Company or any other third party (including, without limitation, any Client).

## Exhibit C: Individual Product Terms/X Marketing Partner (TMP) Program

Capitalized terms not defined in these Individual Product Terms have the meaning set forth in the main body of the Agreement. To the extent that Company participates in the “X Marketing Partner program” (the "**TMP**"), the following terms and conditions of this Exhibit C (including Exhibit C-1) will apply:

### 1. X Marketing Partner Program.

If X approves Company’s application for “Advanced” classification status, and Company maintains such classification status throughout the Term, X may, at any time, choose, in X’s sole and absolute discretion, to qualify Company as part of the TMP (or any other successor program name that X may select from time to time). For clarity, X is not required to select Company to participate in the TMP, regardless of whether Company has achieved or maintains “Advanced” classification status. Furthermore, X may, at any time, choose, in X’s sole and absolute discretion, to terminate or suspend Company’s participation in the TMP for any reason upon notice to Company, in which case, Company’s eligibility to receive any benefits associated with participating in the TMP will immediately cease (without any additional notice from X of such election). In addition to the X Trademark Guidelines that govern Company’s use of any X Marks, Company must also comply with the terms and conditions set forth in Exhibit C-1 that govern use of Badges (as defined in Exhibit C-1) provided by X in connection with participation in the TMP. All Badges (as defined in Exhibit C-1) are deemed X Marks under the Agreement.

### 2. No Use of Badges Outside of the TMP.

For the avoidance of doubt, if Company is not currently qualified by X (in its sole and absolute discretion) as a member of the TMP, (i) Company is not eligible to receive any benefits associated with participating in the TMP, including, without limitation, use of any Badges (as defined in Exhibit C-1) and (ii) Company is prohibited from suggesting it participates in, or has any affiliation with, the TMP.

## Exhibit C-1: X Marketing Partner Program Terms

The X Marketing Partner Program Terms set forth below, including, without limitation, any linked terms and conditions appearing or referenced below, which are hereby incorporated by reference (collectively, “**TMP Partner Terms**”), govern participation in the “X Marketing Partner” program. To the extent that Company is qualified by X, in its sole and absolute discretion, to participate in the “X Marketing Partner” program, Company agrees to abide by the terms and conditions of the TMP Partner Terms at all times during Company’s participation in the “X Marketing Partner” program. These TMP Partner Terms are subject to, and governed by, the Agreement. Any capitalized terms used in this Exhibit C-1 and not otherwise defined in the TMP Partner Terms shall have the meanings ascribed to them in the Agreement.

### 1. TMP Program.

Upon X’s notification to Company that X has qualified Company as a “X Marketing Partner,” Partner will be a member of the “X Marketing Partner” program, as described at [https://business.x.com/en/advertising/partners](https://business.x.com/en/advertising/partners) and will be given access to the TMP badge(s) and any other associated marks that X makes available in connection with the TMP (collectively, the “**Badges**”), use of which is subject to the terms and conditions of this Agreement.

### 2. License from X.

Subject to the terms and conditions of these TMP Partner Terms, and conditioned upon Company’s continuing compliance with this Agreement, X hereby grants Company, and Company accepts, a non-exclusive, royalty free, non-transferrable, non-sub-licensable, revocable license to copy and display the Badges solely with, and to promote, Company’s qualification as a “X Marketing Partner” in the TMP.

### 3. Restrictions.

Strict compliance with this Agreement is required at all times, and any use of the Badges in violation of this Agreement will automatically terminate any license related to Company’s use of the Badges.

**3.1** Company may not alter the Badges in any manner, including, but not limited to, changing the proportion, color or font of the Badges, or adding or removing any elements to or from the Badges.

**3.2** Company may not use the Badges in any manner that implies a false sense of sponsorship or endorsement by X.

**3.3** Company may not use the Badges to disparage X, its products or services, or in a manner which, in X’s sole discretion, may diminish or tarnish X’s goodwill in the Badges.

**3.4** Company may not use the Badges to refer to any other product or service other than X’s or Company’s products and/or services related to Company’s participation in the TMP.

**3.5** The Badges must appear by themselves, with reasonable spacing between each side of the marks, and other visual, graphic or textual elements.

**3.6** The Badges should not be presented or placed in any way that interferes with the readability or display of the entirety of the Badges.

**3.7** Company must link all Badges to [https://business.x.com/en/advertising/partners](https://business.x.com/en/advertising/partners) (or any other successor URL that X may elect from time to time) or otherwise display the following attribution on any materials that display the Badges: “The ‘X Marketing Partner’ Program badge, X and the X logo are trademarks of X Corp. or its affiliates.”

### 4. Program Requirements.

Use of the Badges are further subject to, and governed by, at all times, without limitation, the [X Trademark Guidelines](https://about.x.com/who-we-are/brand-toolkit) and any other requirements communicated by X to Company in connection with participation in the TMP (collectively, the “**TMP Program Requirements**”). Company agrees to the TMP Program Requirements, which are hereby incorporated by reference and are available in hardcopy upon request to X. The TMP Program Requirements do not expand or extend the license to the Badges granted herein. Company may use the Badges solely for the purpose expressly authorized by X, and Company’s use must comply with the most up-to-date version of (i) these TMP Partner Terms, and (ii) the TMP Program Requirements. To the extent that there is any conflict or inconsistency between these TMP Partner Terms and the TMP Program Requirements, these TMP Partner Terms shall control.

### 5. License to X.

Company hereby grants X a fully paid up, non-exclusive, worldwide, sub-licensable license to: (i) use and display Company’s trademarks for use in connection with the TMP, (ii) use Company’s product(s) and/or service(s) related to the TMP for X’s non-commercial, internal evaluation, testing and auditing, (iii) develop and publish case studies or other materials that allow X to highlight Company’s qualification as a “X Marketing Partner” in the TMP (including, without limitation, Company’s product(s) and/or service(s) related to the TMP), and (iv) produce marketing materials in connection with the TMP related to Company’s qualification as a “X Marketing Partner” in the TMP (including, without limitation, Company’s product(s) and/or service(s) related to the TMP).

### 6. Program Qualification.

**6.1 Program Qualification.** X reserves the right, from time to time, to review Company’s membership in the TMP, and, in X’s sole and absolute discretion, to re-qualify or de-qualify Company from any given competency and/or the TMP as a whole.

**6.2 Changes to Company’s Products or Services.** In the event that Company plans to make any material change to Company’s product(s) and/or service(s) related to the TMP, Company will provide X with at least thirty (30) calendar days to review Company’s updated products or services prior to release of such change to determine whether they continue to qualify for the TMP. Updated products or services must be re-qualified by X before any further use of the Badges. X will use commercially reasonable efforts to respond to Company’s request for qualification in new competencies. If Company merges, is acquired or otherwise undergoes a change of control, in whole or in part, by any third party, whether voluntarily or involuntarily, and/or by operation of law (including, without limitation, in connection with a merger, acquisition, or sale of assets, whether the assigning party is the surviving or disappearing entity), Company must submit all of Company’s products and/or services related to the TMP to X for re-qualification before any further use of the Badges.

### 7. Suspension and Termination.

X may immediately terminate or suspend these TMP Partner Terms, any rights granted to Company herein, and/or Company’s participation in the TMP, at its sole discretion at any time, for any reason by providing notice to Company. Company may terminate Company’s participation in the TMP by providing ninety (90) calendar days’ notice to X. Upon termination of these TMP Terms and/or termination of Company’s participation in the TMP, all licenses granted herein immediately expire, and Company must cease use of all Badges. Neither party will be liable to the other for any damages resulting solely from termination of these TMP Partner Terms as permitted under this Agreement.

### 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.


# X Developer Agreement
Source: https://docs.x.com/developer-terms/agreement

The X Developer Agreement sets the legal terms for using the X API and developer platform, covering licensing, restrictions, and compliance obligations.

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.

This X Developer 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).

By accessing or using any Licensed Material (defined below), or clicking on a button to accept the terms of this Agreement or recurring subscription payment for Paid Services, you agree to be bound by the terms of this Agreement. If you do not understand the terms herein or do not accept any part of them, then you may not use or access any Licensed Material. You may not use the Licensed Material or accept this Agreement if you are not of legal age to form a binding contract with X or if you are barred from using or receiving the Licensed Material under applicable law. To purchase and use a Paid Service you must: (i) be at least 18 years old or the age of majority as determined by the laws of the jurisdiction in which you live or (ii) have the express consent of your parent or guardian to purchase and use that Paid Service. If you are a parent or legal guardian and you allow your child (or a child that you are a guardian of) to purchase or use a Paid Service, you agree that the terms of this Agreement apply to you, you will abide by this Agreement, and you are responsible for the child’s activity on the Paid Services and for ensuring that the child also abides by the terms of this Agreement. In any case, as stated in the Who May Use the Services section of the [**X Terms of Service**](https://x.com/tos), you must be at least 13 years old to use the "Services" as defined in the X Terms of Service. If you are accepting this Agreement or using the Licensed Material on behalf of a company, organization, government, or other legal entity, you represent and warrant that you have the authority to bind such company, organization, government, or other legal entity to this Agreement, in which case the words “you” and “your” as used in this Agreement shall refer to such entity. If you do not agree to the terms of this Agreement, you may not (and you may not allow any of your personnel to) access or use the Licensed Material.

**I. Definitions.**

In this Agreement, the following definitions apply:

1. “**Developer Site**” means X’s developer site located at [**https://developer.x.com/**](https://developer.x.com/)
2. “**Direct Message**” means a private message that is sent on X Applications by one user to one or more other specific user(s) using X’s direct messaging function.
3. “**Intellectual Property Rights**” means all copyrights, moral rights, patent rights, trademarks, and any other intellectual property or similar rights (registered or unregistered) throughout the world.
4. “**Licensed Material**” means, individually or collectively, the X API and X Content.
5. "**Paid Service(s)**” means features or functionality of the Licensed Material that you access in exchange for payment of a recurring fee, as applicable to the relevant features or functionality and this Agreement. Unless otherwise set forth in this Agreement, all references to “Licensed Material” are intended to include the Paid Service(s).
6. “**Payment Portal**” means the online portal made available to you to opt-in to your use of the Licensed Material, manage subscriptions for Paid Services, manage payment methods for Paid Services, and update account information.
7. “**Services**” means your services, websites, applications, and other offerings (including research) that display X Content or otherwise use the Licensed Material.
8. “**Post**” means a short-form text and multimedia-based message distributed via the X Applications.
9. “**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.
10. “**X API**” means X Application Programming Interfaces (each, an **“API”**), Software Development Kits (each, an **“SDK”**), and the related tools, documentation, data, technology, code, and other materials provided by X through the Developer Site.
11. “**X Applications**” means X’s real-time information service, commonly referred to as “X,” which includes those services currently provided by X at its websites and X-owned, operated, or controlled mobile applications, social plug-ins, and application programming interfaces.
12. “**X Content**” means Posts, the unique identification number generated for each Post, X end user profile information, and any other data and information made available to you through the X API or by any other means authorized by X, and any copies and derivative works thereof.
13. “**X Marks**” means the X name, trademarks, and logos that X makes available to you, including via the Developer Site, solely for use in accordance with this Agreement.
14. “**Users**” means visitors, users, or customers of your Services.

**II. X API and X Content.**

**A. License from X.** Subject to your compliance with the terms of this Agreement and the applicable Incorporated Developer Terms (as defined below), X hereby grants you a non-exclusive, royalty free, non-transferable, non-sublicensable, and revocable license to solely:

1. Use the X API to integrate X Content into your Services or conduct analysis of the X Content, as explicitly approved by X;
2. Copy a reasonable amount of and display the X Content on and through your Services to Users, as permitted by this Agreement;
3. Modify X Content only to format it for display on your Services; and
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).

**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**](/developer-terms/policy);
2. the [**API Restricted Use Rules**](/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);
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.**

**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).

**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, and 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 otherwise does not comply with this Agreement. If you exceed or X reasonably believes that you have attempted to circumvent Rate Limits, controls to limit use of the X APIs, or the terms 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.

**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.

**F. Use of X Marks.** You shall not include any of the X Marks in your registered corporate name(s), your logos, or your service or product names. You shall not create any derivative works of the X Marks or use the X Marks in a manner that creates or reasonably implies an endorsement, sponsorship, or association with X. All use of the X Marks and all goodwill arising out of the use will inure to X's benefit. You will not remove or alter any proprietary notices or X Marks on the Licensed Material.

**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.

**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](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).

**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.

**B. Removals.** If X Content is deleted, gains protected status, or is otherwise suspended, withheld, modified, or removed from the X Applications (including removal of location information), you will make all reasonable efforts to delete or modify that X Content (as applicable) as soon as possible, and in any case within twenty four (24) hours after a written request to do so by X or by an X user with regard to its X Content unless prohibited by law or regulation and with the express written permission of X.

**V. Ownership, Betas, and Feedback.**

**A. Ownership.** Except to the extent expressly stated otherwise in this Agreement, neither party will acquire any right, title, or interest in any Intellectual Property Rights owned or licensed by the other party. The Licensed Material is licensed, not sold, and X (or its licensors or X Application users, as applicable) retains and reserves all rights, including all Intellectual Property Rights, not expressly granted in this Agreement. You shall not do anything inconsistent with X’s ownership, including without limitation, challenging X’s ownership of the X Marks, challenging the validity of the licenses granted in this Agreement, or otherwise copying or exploiting the X Marks except as specifically authorized in this Agreement. If you acquire any rights in the X Marks or any confusingly similar marks, by operation of law or otherwise, you will, at no expense to X, immediately assign those rights to X.

**B. Betas.** X may provide you with early access to non-generally available alphas, betas, research studies, pilots, marketing services, or other programs from time to time (each, a “**Beta**”). Betas will be considered Confidential Information. Your participation in any Beta is at your own risk, may be subject to additional requirements, and may assist X in research, analyzing, and validating existing or prospective programs, products and/or tools.

**C. Feedback.** X will be free to use any feedback, comments, or suggestions you provide X related to X, the Licensed Material, Betas, or any other of X’s products or services (“**Feedback**”) in any way without any compensation or obligation to you or any third party and Feedback will be deemed Confidential Information. You hereby irrevocably assign to X all right, title, and interest to Feedback.

**VI. Confidentiality.**

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; Subscription Fees; Payment; 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. Subscription Terms.** Paid Services provided as part of the Licensed Material are made available as a recurring subscription service that provides access to certain features, benefits, or services, as described on the Developer Site and the Payment Portal. If you purchase a Paid Service, you do so by paying a subscription fee in advance on a monthly basis in accordance with the payment terms set forth below. When you subscribe to access the Paid Service(s) via the Payment Portal, you expressly agree that you are authorizing recurring payments and that payments will be made by the payment method you have selected until the applicable Paid Service is canceled by you or by X or this Agreement is otherwise terminated. Your subscription to the Paid Service will automatically renew monthly until canceled in accordance with this Agreement. Your payment information will be automatically processed by the Payment Processor (as defined below) at the start of each subscription period applicable to the Paid Service(s). If your payment information is declined, your subscription may be canceled until you provide new payment information for the applicable Paid Service(s). If you provide new payment information and your payment account is successfully charged, your new subscription period will be based on the original renewal date and not the date the successful charge took place. Prices for Paid Services are subject to change from time to time. X will provide reasonable advance notice of any material change to the price of Paid Services, which notice may be provided via the Developer Site. For subscription fees, price changes will take effect at the start of the next subscription period following the date of the price change. If you do not agree with a price change, you have the right to reject the change by canceling your subscription to the applicable Paid Service(s) prior to the price change going into effect.

**C. 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 the Paid Service, along with any additional amounts relating to applicable taxes, surcharges, credit card fees, bank fees, foreign transaction fees, foreign exchange fees, and currency fluctuations, on a recurring basis during the applicable subscription period; 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 subscription fee will automatically be applied at the start of the renewal period for the applicable subscription period unless you cancel the Paid Service(s) on the Developer Site. It is your responsibility to 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, when a subscription is set to expire or auto-renew, 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.

**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. Canceling Your Subscription for Paid Services.** Your subscription for Paid Services will automatically renew monthly unless you cancel your subscription at least 24 hours before the end of your current subscription period. There are no refunds or credits for any partial subscription periods, including in a situation where certain features, benefits, and/or services are modified or discontinued. SUBSCRIPTION PLANS ARE PREPAID, NON-REFUNDABLE (UNLESS REQUIRED BY LAW), AND AUTOMATICALLY RENEW AT THE END OF EACH SUBSCRIPTION PERIOD UNLESS THE SUBSCRIPTION IS CANCELED FOLLOWING THE CANCELLATION PROCEDURES HEREIN. You may cancel your subscription for Paid Services at any time via the Developer Site and you will no longer have access to the Paid Services (or any features or functionality thereof) at the end of your then-current subscription term. When you cancel the Paid Services, your subscription will remain active from the time you cancel until the end of your current subscription period. You will not receive a refund or credit for any remaining days in your current subscription period unless required by law. All payments for Paid Services are final and not refundable or exchangeable except as required by applicable law. X makes no guarantee as to the nature, quality, or value of a Paid Service or the availability or supply thereof. Refunds or credits are not provided for any unused or partially used Paid Service (for example, a partially used subscription period). **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.** When you purchase any Paid Services on subscription, you expressly agree to do so on a subscription basis and that the subscription will commence immediately on your date of purchase. If you are a consumer in an EU Member State or the UK, you agree you have fourteen (14) days after your purchase to withdraw from your contract for purchase for any reason.
2. **No Withdrawal Right for Users Living in Taiwan.** When you purchase Paid Services, you do so on a subscription basis, the subscription will commence immediately on your date of purchase, and the Paid Service is fully performed once started. If you are a consumer in Taiwan, you agree that you can cancel your subscription for any Paid Services in accordance with Section VII.E above, but that there is otherwise no right to rescind your subscription and no refund will be issued.

**F. Paid Services Are Non-Transferable between X Accounts.** Each purchase of a Paid Service applies to a single X account, meaning that your purchase will apply solely to the account you were using when you purchased the Paid Service 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 Paid Service 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 a Paid Service 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 a Paid Service or 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 Paid Service or Licensed Material. X may, in its discretion, restrict the ability to access the Licensed Material or purchase a Paid Service in certain countries. X reserves the right to modify the list of supported countries from time to time. X reserves the right to refuse Paid Services transactions 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. Except where such early termination is the result of your breach of this Agreement, such early termination by X shall be effective at the end of the then-current subscription period. 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 prorated refund for any Paid Services. You may cancel your subscription for the Paid Services or your use of the Licensed Material on the Developer Site. 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.**

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.**

**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.

**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.**

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

**XIV. Miscellaneous.**

**A. Assignment.** You shall not assign any of the rights or obligations granted hereunder, in whole or in part, whether voluntarily or by operation of law, contract, merger (whether you are the surviving or disappearing entity), stock or asset sale, consolidation, dissolution, through government action, or otherwise, except with the prior written consent of X. X is authorized to sign modifications and consents for X Internet Unlimited Company, an Irish company responsible for the information of X users who live outside the United States. Any attempted assignment in violation of this Section will be null and void and X may terminate this Agreement.

**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](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.

**E. Data Protection Addendum.** Each party shall comply with the X Controller-to-Controller Data Protection Addendum located at [**https://gdpr.x.com/en/controller-to-controller-transfers.html**](https://gdpr.x.com/en/controller-to-controller-transfers.html), which may be updated by X from time to time.

**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.


# Display requirements: Posts
Source: https://docs.x.com/developer-terms/display-requirements

Display requirements for showing X Posts in your app, including branding, attribution, anatomy of a Post, interactivity, and metadata to render.

## General principles and Post anatomy

Posts are one of our most visible brand elements, so it’s important that they are presented correctly. You should comply with the display requirements below when you display posts, timelines, and other X content.

If you follow these guidelines merely to display a post, you may not need to contact X for any additional display or trademark permissions. However, you may still want to submit your proposed use and context for X review. (Note that, in some cases, permission from the original content creator may still be necessary, as X does not provide permission to use third party/user content.)

The following general principles apply to all display mediums. Please note, medium-specific requirements do apply, and are outlined in the sections below.

The image below shows all the main components of a post.

<img alt="Post Anatomy" />

### Do

* Display real, unmodified posts from real accounts.
* Follow X’s [Terms of Service](https://x.com/tos?lang=en), the [X Brand Assets and Guidelines](https://about.x.com/en_us/company/brand-resources.html), and (if applicable) the [Developer Agreement and Developer Policy](/developer-terms/agreement).
* Display the X logo.

### Don't

* Use X content to promote any product or service (e.g., by displaying X content in advertising or otherwise displaying X content to imply endorsement of any product or service) without explicit permission from the user.
* Use X content to imply sponsorship by, endorsement from, or a false association with X.
* Include buttons or icons from other social platforms.
* Modify post text.
* Use mock ups of posts that don’t exist on the platform.

***

## Online display / Mobile, web, and beyond

We’re committed to bringing the ease and power of X to everyone. To ensure every post is displayed optimally, we strongly encourage using [embedded posts and/or embedded timelines](https://publish.x.com). When you use these products to publish X content, posts and timelines are automatically rendered correctly, including advanced features like photos, video playback, edited posts, and fetching of up-to-date X data without OAuth. If it is not possible for you to use our embedding features, you must follow the requirements below when displaying posts and timelines online.

<img alt="Post Display" />

### Post author

* The post author’s profile picture, @username, and display name must always be displayed and link to the user’s X profile.
* The post author’s @username must always be displayed with the “@” symbol.
* The post author’s avatar must be positioned to the left of the author’s name and @username—except for posts in languages that read right to left, in which case the author’s avatar must be positioned to the right of the author’s display name and @username.

### Post text

* The post text must be displayed on a line below the author’s display name and @username, and may not be altered or modified.
* On touch devices, the white space around the post text and post author must link to the post’s permalink.
* Post entities within the post text must be properly linked to their appropriate home on X. For example:
  * User @mentions must link to the mentioned user’s profile.
  * Hashtags must link to a X search with the hashtag as the query.
  * Links in post text must be displayed using the display\_url field in the URL entities API response, and link to the original t.co url field.

### Timestamp

* The post timestamp must be displayed and link to the post’s permalink.

### Post Actions

* All post Action icons (including reply, repost, and like) must always be visible for the user to interact with the post. These actions must be implemented using [Web Intents](/x-for-websites/web-intents/overview) or with the authenticated X API. In lieu of post Actions, “View on X” may be shown next to the timestamp, linking the user to the post permalink.
* No other social or third party actions may be attached to a post. (e.g., subscribe, comment, like).
* If the post being displayed is a repost, the display name of the user who reposted it and the repost icon must be displayed above or under the post text. e.g., “reposted by Jane Doe”. The display name must link to the profile of the user who reposted it.
* Follow [guidelines for displaying replies](/developer-terms/reply-requirements).

### Post edits

* X allows people to edit their posts up to 5 times during the first 30 minutes after posting the original post.  When using [embedded posts](/x-for-websites/embedded-posts/overview), the display will appear slightly different depending on whether the post was edited before or after it was embedded.
* When a post is embedded first, and then edited, you must display those edits as they occur on the X platform:
* If you are displaying a previous version of an edited post, you must note below the timestamp that there is a new version of the post, and to the right of that note, provide a link which expands the post’s edit history.
* You must then display the full edit history of the post.

When a post has been edited first, and then embedded, you must note in the timestamp that the post was edited, and the timestamp must also link to the live post on X.

### Branding

* The official X logo must always be reasonably visible and displayed on the upper-right corner of an individual post or directly attached to the timeline (e.g., top of the timeline). The logo should be the same height “x” as in the image. See X’s [brand resources page](https://about.x.com/en_us/company/brand-resources.html) for brand guidelines and assets.

### Mobile deep linking

* Deep links from native mobile apps must direct to the native X application. If the native X application is not installed on the device, the link must direct to X.com via a web browser.

### Timelines

* All timelines must allow users to view the details of an individual post (e.g., by linking the post timestamp or by linking the entire post area).

If you plan any advertising near posts, please ensure it complies with the [Developer Policy](/developer-terms/policy).

If for any reason you cannot comply with one or more of these rules, please contact us directly via our [Policy Support form](https://help.x.com/forms/platform) before displaying X content. For questions or further information about use of the X name and trademarks, please contact [trademarks@x.com](mailto:trademarks@x.com).

***

## Broadcast display / 15 minutes of fame

We welcome and encourage the use of X in broadcast media. Our requirements ensure that X users receive proper attribution for their content, and help provide the best experience for your audience.

<img alt="Post Broadcast" />

### Do

* Show the user’s full name, @username, post text, and profile picture.
* Include the X logo in close proximity to the posts for as long as they appear in your broadcast. Make sure that the X logo is sized similarly to the size in the above image, relative to the content.
* Use the full text of the post.
* When displaying images, the post text must also be included along with the user’s display name, @username, and the X logo.

### Don't

* Display X content in advertising or to imply endorsement of any product or service without explicit permission from the user.
* Delete, obscure, or alter the post content or identification of the user (with the exception of removing hyperlinks).
* Exclude the timestamp.
* Do not use X marks, in whole or in part, in the title of your production without first reviewing their use with X by contacting us at [trademarks@X.com](mailto:trademarks@X.com).

***

## Verbal or voice over

### Posts

When reading posts on air with no graphic display of the post, you do not need to display the X logo but you do need to verbally attribute it to X. Read the post as originally written, without edits.

### Usernames

Make sure to include a reference to X when mentioning X usernames. For example, “Follow us on X, at-username” or “You can follow Lady Gaga on X, at-ladygaga”

### Hashtags

Make sure to include a reference to X when mentioning X hashtags. For example, “Use the hashtag ‘election2016’ on X” or “The hashtag for this broadcast on X is bbcaq”.


# Geo guidelines
Source: https://docs.x.com/developer-terms/geo-guidelines

Guidelines for handling geotagged Posts and location data from the X API, including geo features, place objects, and user privacy considerations.

Last Update: October 22, 2014.

## Introduction

Posting With Location is the geotagging feature in the X API. This feature helps to provide a more meaningful experience for users by making posts more contextual. For instance, “Fireworks!” is much more relevant when associated with a location: “Fireworks!” from the SoMa Neighborhood in San Francisco, California. We look forward to working with the developer ecosystem to create great experiences around this functionality!

## User privacy and user control of their location information

To ensure a good and safe experience, developers should be sensitive to user privacy when dealing with their location as well as provide baseline consistency in the “Posting with Location” experience. Here are some key things to keep in mind that help protect user privacy and ensure users understand the impact of their actions:

## General guidelines

* Users must opt-in to use the Posting With Location feature (turn location “on”).
* Users must give explicit permission for their exact location to be displayed with their posts. If the location feature on your client is “sticky” — i.e. once location is turned on it always accompanies a post — you may wish to display only place names (place\_ids) and allow users to further opt in to exact latitude and longitude on a per-post basis or as a specific alternative setting.
* When you access your users’ location data to post a post, that information should not be stored by you apart from the post without the user’s explicit permission.
* It must be clear to users what level of location information, if any, will be displayed in association with their post. One way you can do this is by showing a map of how this information will be displayed before the post is published. If exact latitude and longitude is part of the information (or the only information) published by the user on the client, it should be clear to the user that their exact coordinates will be published.
* Users should be able to turn on and off their location each time they compose a post.
* You must follow the terms of X’s [Developer Policy](/developer-terms/policy.html) – including the requirement that you may not aggregate, cache, or store location data and other geographic information from the X API, except as part of a post, and may not use such location data or geographic information on a standalone basis.

## Specific examples

Example 1: *No addition of explicit latitude and longitude (this is the current X Web Client UI)*

1. Show a link to “Add your location” when a user composes a post;
2. In the background, use the X [reverse\_geocode](https://developer.x.com/en/docs/geo/places-near-location/api-reference/get-geo-reverse_geocode.html) API call and pass the latitude, longitude, accuracy of your fix, and the user’s preferred granularity (which, by default, is “neighborhood”);
3. Display the name for the default place (X will attempt to order these in a way that makes sense - the ordering is such that a X client can just display the list without a need for modification);
4. Allow the user to select a different location from the list (e.g. change from “SoMa, San Francisco” to “South Beach, San Francisco”).
5. Important: Be transparent with the user if you will be displaying exact location information. Make sure the user knows if exact location information will be displayed.
6. Allow the user the choice to turn on or off location with every post compose.

Example 2: *Existing geotagging implementations*

A number of X client apps have the original geotagging feature (which only broadcast lat/lons without providing place\_IDs) implemented. The default behavior of the API mimics this behavior – i.e. as a developer you do not need to make any changes to your existing app in order to maintain the behavior that exists today. Indeed, if you simply pass a lat/lon coordinate in to X, X will automatically reverse geocode that latitude and longitude and display the place\_ID in addition to lat/lon for areas where we have data available.

Ensure that it is transparent to your users that their exact coordinates are being used and displayed on X. A best practice for existing apps would be to allow users to turn on or off their location on a per-post basis. You can also enable your users to share only place\_IDs instead of exact coordinates as a default, “sticky” setting.

## X storage of user location data

X will store data passed by the client as follows:

* X will save all the data that a user chooses to publicly display to his/her followers. This is similar to how X stores the time stamp that says when the post was made, meaning if a user posts with their exact coordinates, X will store this exact location along with the post for as long as the post exists. Users can clear location data from their posts by clicking the “clear my location history” button on the Settings page as described [here](https://support.twitter.com/articles/122236-how-to-tweet-with-your-location).

## Summary

The addition of location to a post adds an enormous amount of context and value from a user perspective. However, implementations of location in your client should be careful to take privacy and user transparency as a key consideration in designing a location-focused product.

If you have any questions or comments about privacy, location, and other geo features, please [contact us.](https://support.twitter.com/forms/platform)


# X Developer Policy
Source: https://docs.x.com/developer-terms/policy

The X Developer Policy outlines acceptable use of the X API, including rules around content, automation, privacy, security, and prohibited behaviors.

## X + Developers

X loves developers. We’re delighted and amazed by the tools and services this community creates by harnessing the power of X data. As part of our commitment to this community, we aim to provide data access that is open and fair for developers, safe for people on X, and beneficial for the X platform as a whole. To further these goals we’ve crafted the Developer Policy as a guide to help people understand our rules and expectations about appropriate API and X Content usage.

This Developer Policy (“**Policy**”) provides rules and guidelines for developers who interact with X’s ecosystem of applications, services, website, web pages and content. It is part of your contract with X governing access to and use of the X API and X Content (either as part of the Developer Agreement or other written agreement with X). Policy violations are considered violations of your agreement. This Policy may be changed from time to time without notice. Capitalized terms used in this Policy, which are not defined in this Policy, will have the respective meanings ascribed to them in the [Developer Agreement](/developer-terms/agreement) or the Master License Agreement.

## Using this policy

We’ve structured this policy to make it as easy to follow as possible. Please keep information from the following policy sections top of mind as you use the X API and X Content:

1. **Follow the Platform Usage Guidelines** - Getting approved to access the X API and X Content is just the first step. Our Platform Usage Guidelines should be your first stop anytime you have questions about how to ensure policy compliance for your planned use of the X platform.
2. **Set Yourself Up for Success** - You are responsible for complying with all X policies. It’s important that you review and understand this Policy, as well as the policies we link to in this document, before you access the X API and X Content. The time spent reviewing our policies may save you hours of rework down the road.
3. **Privacy and Control are Essential** - Protecting and defending the privacy of people on X is built into the core DNA of our company. As such, we prohibit the use of X data in any way that would be inconsistent with people’s reasonable expectations of privacy. By building on the X API or accessing X Content, you have a special role to play in safeguarding this commitment, most importantly by respecting people’s privacy and providing them with transparency and control over how their data is used.

We’ve provided a lot more detail on what each of these three key sections mean below. Please review them carefully to ensure that your usage of the X API and X Content is consistent with our policies.

If we believe you are in violation of this Policy (or any other X policy), we may suspend or permanently revoke your access to the X API and X Content.

Finally, please note that X may monitor your use of the X API to improve the X Applications, to examine any commercial use, and to ensure your compliance with your approved use case and this Policy.

Thanks for reading, and thank you for building with us! We look forward to seeing what you create!

## Platform usage guidelines

Have you taken care to review X’s policies and set up your API access the right way? Does your service follow X’s privacy and control guidelines? If you can answer yes to these two questions, then you are ready to start using the X API and X Content. X’s Platform Usage Guidelines provide the assistance needed to ensure that your use of X Content is compliant from day 1 throughout the lifecycle of your service. We suggest reviewing these rules on a regular basis to make sure that your integration is operating in a way that is safe and beneficial to people on X and the X platform as a whole.

## Spam, bots, and automation

**The use of the X API and developer products to create spam, or engage in any form of platform manipulation, is prohibited.** You should review the X Rules on [platform manipulation and spam](https://help.x.com/rules-and-policies/platform-manipulation), and ensure that your service does not, and does not enable people to, violate our policies.

[**Services that perform write actions, including posting Posts, following accounts, or sending Direct Messages, must follow the Automation Rules.**](https://help.x.com/rules-and-policies/x-automation) In particular, you should:

* Always get explicit consent before sending people [automated replies or Direct Messages](https://twittercommunity.com/t/policy-clarification-automated-replies-and-mentions/94444)
* Immediately respect 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)

**If you’re operating an API-based bot account you must clearly indicate what the account is and who is responsible for it.** You should never mislead or confuse people about whether your account is or is not a bot. A good way to do this is by including a statement that the account is a bot in the profile bio.

## X performance benchmarking

**You may not use the X API to measure the availability, performance, functionality, or usage of X for benchmarking, competitive, or commercial purposes.** For example, you should never use the X API to:

* Calculate aggregate X metrics, such as the total number of Monthly Actives (MAs) or Daily Actives (DAs)
* Calculate aggregate X Post metrics, such as the total number of Posts posted per day, or the number of account engagements
* Measure or analyze the responsiveness of X
* Measure or analyze spam or security on X, except as permitted below

**We support research that helps improve conversational health on X.** You may not publicly disclose any research or findings concerning, or develop, create, or offer services using, the X API or X Content that measure, analyze, or attempt to identify behaviors or content which violate X policies without express written permission from X.

**DSA Researchers:** If you need to contact X relating to access under Art. 40 of the Digital Services Act, please contact [**EU-Questions@X.com**](mailto:EU-Questions@X.com). If you wish to apply for researcher access, please submit an [application](https://forms.gle/btDwenPF7M3hgSvw7).

## Public display of Posts

**You must maintain the integrity of all X Content that you display publicly or to people who use your service.** If you don’t use [X for Websites](https://developer.x.com/docs/twitter-for-websites/overview) to display content, then you must use the X API to retrieve the most current version available for display. If displayed content ceases to be available through the X API, then you must remove it from your service as soon as reasonably possible, or within 24 hours after the receipt of a removal request from X, or the applicable X account owner, or as otherwise required by applicable law.

**There are specific rules you must follow if you display X Content offline.** Follow the [guidelines](https://developer.x.com/developer-terms/display-requirements) for using Posts in broadcast if you display Posts offline.

**If you embed or display Posts, you must contact us about your X API access if your site exceeds 10 million daily impressions.** X reserves the right to require additional terms as a condition to your use of the X API. Additional restrictions on X for Websites developer use include:

* **Embedded Posts and/or embedded timelines**
  * You must provide people with legally sufficient notice that fully discloses X’s collection and use of data about browsing activities on your website, including for interest-based advertising and personalization. You must also obtain legally sufficient consent from people for such collection and use
  * You must provide legally sufficient instructions on how people can opt out of X’s interest-based advertising and personalization as described [here](https://help.x.com/x-for-websites-ads-info-and-privacy)
* **X for Websites widgets**
  * You must ensure that people are provided with clear and comprehensive information about, and consent to, the storing and accessing of cookies or other information on their devices as described in X’s [cookie use](https://help.x.com/rules-and-policies/x-cookies), where providing such information and obtaining such consent is required by law
* **Services targeted to children under 13**
  * Services targeted to children under 13 must opt out of tailoring X in any embedded Post and/or embedded timelines by setting the opt-out parameter to be ‘true’ as described [here](https://developer.x.com/docs/twitter-for-websites/privacy)

## Content redistribution

**The best place to get X Content is directly from X. Consequently, we restrict the redistribution of X Content to third parties.** If you provide X Content to third parties, including downloadable datasets or via an API, you may only distribute Post IDs, Direct Message IDs, and/or User IDs (except as described below).

In total, you may not distribute more than 1,500,000 Post IDs to any entity (inclusive of multiple individuals associated with a single entity) within any 30 day period unless you have received written permission from X. In addition, developers may provide up to 500 public Posts Objects and/or User Objects to each person who uses your service on a daily basis if this is done via non-automated means (e.g., download of spreadsheets or PDFs).

Academic researchers are permitted to distribute Post IDs and/or User IDs solely for the purposes of non-commercial research on behalf of an academic institution, and that has been approved by X in writing, or peer review or validation of such research. Only as many Post IDs or User IDs that is necessary for such research, and has been approved by X may be used.

Any X Content provided to third parties remains subject to this Policy, and those third parties must agree to the X [Terms of Service](https://x.com/tos), [Privacy Policy](https://x.com/privacy), [Developer Agreement](/developer-terms/agreement), and [Developer Policy](/developer-terms/policy) before receiving such downloads. You may not enable any entity to circumvent any other limitations or restrictions on the distribution of X Content as contained in this [Policy](/developer-terms/policy), the [Developer Agreement](/developer-terms/agreement), or any other agreement with X.

**Note:** This Section does not apply to researchers with X API access via Art. 40 of the EU Digital Services Act (2022) (“**DSA**”), who are instead subject to the procedures and restrictions set forth in the DSA and the Developer Agreement.

## Pay to engage

**Your service shouldn’t compensate people to take actions on X, as that results in inauthentic engagement that degrades the health of the platform.** As you use the X API you may not sell or receive monetary or virtual compensation for any X actions. This includes, but is not limited to, Posts, follows, unfollows, reposts, likes, comments, and replies.

## Service authenticity

**You must clearly identify your service so that people can understand its source and purpose.** Don’t use names, logos, or URLs that mask your service’s identity and features, or that falsely imply an affiliation with X or third parties. Note that creating applications for the purpose of selling names, or to prevent others from using names, is prohibited.

**You may not use any URL (including shortened URLs) for your service that directs people to:**

* A site that is unrelated to your service
* A spam or malware site
* A site that encourages people to violate X policy

## X name, logo, and likeness

**You may only use and display the X name and logo to identify X as the source of X Content.** You should never use the X name and logo, the X Official Partner Program badge, or any other similar marks or names in a manner that creates a false sense of endorsement, sponsorship, or association with X. The X [Brand Resources](https://about.x.com/who-we-are/brand-toolkit) contain detailed information to help you use the X brand in the right way.

**You may only use the X Verified Account badge and any other enhanced account categorization as it is reported to you by X through the API.** This helps people know that the content your service displays is equivalent to that shown on X.

## Advertising on X

**There are restrictions regarding how and where you are allowed to advertise around X Content.** To start, your advertisements can’t resemble or reasonably be confused by people as a Post. Other rules on advertising include:

* **There must be a clear separation between X Content and your advertisements.** You may not place any advertisements within the X timeline other than X Ads.
* **X reserves the right to serve advertising via the X API.** If you decide to serve X Ads once we start delivering them via the API, we will share a portion of advertising revenue with you in accordance with the relevant terms and conditions.
* **You may not use X Content, or information obtained from the X API to target people with advertising outside of the X platform.**

The following additional rules apply for any use of the X services or features listed below:

## X Login

**You must present people with easy to find options to log into and out of X, for example via the OAuth protocol.** The *Sign in with X* option must be displayed at least as prominently as any other sign-up or sign-in feature on your service. You must also provide people without a X account the opportunity to create one via X.

***Once someone on your service authenticates via Sign in with X you must clearly display their X identity.*** X identity includes the person’s current X @handle, avatar, and X logo. Any display of someone’s X followers on your service must clearly show that the relationship is associated with X.

X reserves the right to monitor the total number of unique users who have authenticated or logged in via Sign In with X (or other X authentication methods) to your products, services, or those made available by or for you or your affiliates and, in the event that total number greatly exceeds the normal levels of other developers subscribed to a similar tier of service, you must apply (or already subscribe) to an Enterprise plan upon written notice from X.

You agree that X may, from time to time, review your *Sign in with X* option and, in its sole discretion, remove this X feature from your service.

## X Cards

**To ensure a quality experience you must develop your Card to render across all platforms where Cards are displayed.** Additional rules that you must follow when using Cards include:

* You must mark your Post as ‘true’ for sensitive media if you plan to display such media within a Card
* You must use HTTPS for hosting all assets within your Card. Your Card should never generate active mixed content browser warnings
* Audio and video content should include stop or pause controls, and default to ‘sound off’ for videos that automatically play content

**You may not exceed or circumvent X’s limitations placed on any Cards, including the Card’s intended use.** Additional restrictions on Cards use include:

* You may not place third-party sponsored content within Cards without X’s approval
* You may not attach monetary incentives (including virtual currency) within your Card or on X from your Card
* You may not include content or actions within your Card that are misleading or not contextually relevant, such as URLs and media.
* You may only attach an App Card to a Post when someone is explicitly promoting or referring to the app in the Post.

## Set yourself up for success

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](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.

Your use case description is binding on you, and any substantive deviation from it may constitute a violation of our rules and result in enforcement action. You must notify us of any substantive modification to your use case and receive approval before you may begin using X Content for that new purpose. Failure to do so may result in suspension and termination of your API and data access.

**By building on the X API or accessing X Content, you must comply with ALL X policies.** These include this [Developer Policy](/developer-terms/policy), the [Automation Rules](https://help.x.com/rules-and-policies/x-automation), the [Display Requirements](https://developer.x.com/developer-terms/display-requirements.html), the [API Restricted Uses Rules](/developer-terms/restricted-use-cases), the [X Rules](https://help.x.com/rules-and-policies/x-rules), and the [X Brand Resources](https://about.x.com/who-we-are/brand-toolkit), as well as any other agreements you enter into with X relating to your use of the X API or X Content, including but not limited to the [Developer Agreement](/developer-terms/agreement) or a Master Licensing Agreement or Order (as applicable). You must also comply with any modifications to these policies and any new policies launched by X. It is your responsibility to monitor the use of your service and to design your service to prevent violations of X policy by people who use it. Failure to do so may result in suspension or termination of your API and X Content access.

**You may not register multiple applications for a single use case or substantially similar or overlapping use cases.** In this context, a “use case” is a consistent set of analyses, displays, or actions performed via an application. "White label" versions of a tool or service are not permissible. If you plan to “white label” versions of your application, you must notify and receive separate approval from us.

*As a single exception to these rules,* you may create and use a maximum of 3 applications for development, staging, and production instances of the same service. These apps must be registered to a single account, and should be clearly identified (in the name and description) as dev, staging, and prod instances of a single service. **You may not use development or staging applications for production purposes.**

**You must keep all API keys or other access credentials private.** You may not use, and may not encourage or facilitate others to use, API keys or other access credentials owned by others.

**Your license agreement with X limits your use of the X API and X Content. Among other things, the X API has rate limits which help to ensure fair data usage and to combat spam on the platform.** You may not exceed or circumvent rate limits, or any other limitations or restrictions described in this Policy or your agreement with X, listed on the [Developer Site](https://developer.x.com/), or communicated to you by X.

**You may not remove or alter any proprietary notices or marks on X Content received via the X API.** This helps to make sure that people know where X Content is coming from, and who it belongs to.

**For data integrity and platform health reasons, you may not interfere with, intercept, disrupt, or disable any features of the X API or the X service.** In other words, use the APIs as intended and documented on [developer.x.com](https://developer.x.com/). Refer to our [HackerOne guidelines](https://hackerone.com/x) for more details about acceptable use.

## Privacy and control are essential

X takes privacy seriously, and we expect everyone using X Content and the X API to do the same. Any use of the X developer platform, X API, or X Content in a manner that is inconsistent with people’s reasonable expectations of privacy may be subject to enforcement action, which can include suspension and termination of API and X Content access.

Your commitment to privacy and control must extend to all uses of X Content and all aspects of the service that you build using our API. To that end, the people using your service must understand and consent to how you use their data, and how you access X on their behalf. This can be accomplished through providing people with a clear, comprehensive, and transparent privacy policy, as well as ensuring that you get express and informed consent from each person using your service before taking any action on their behalf. **Please note that a person authenticating into your service does not by itself constitute consent.**

## Consent & permissions

**In particular, you must get express and informed consent from people before doing any of the following:**

* Taking *any* actions on their behalf. This includes (but is not limited to):
  * Posting content to X
  * Following/unfollowing accounts
  * Modifying profile or account information
  * Adding hashtags or any other content to Posts
* Republishing content accessed by means other than via the X API or other X tools
* Using someone’s X Content to promote a product or service
* Storing non-public content such as Direct Messages (DMs), or any other private or confidential information
* Sharing or publishing protected content, or any other private or confidential information

**If your service allows people to post content to X you must do the following before publishing:**

* Show exactly what will be published
* Make it clear to people using your service what geo information (if any) will be added to the content

**If your service allows people to post content to both your service and X, you must do the following before publishing:**

* Obtain permission to post the content
* Explain where you will post the content

**You must respect the protected and blocked status of all X Content. You may not serve content obtained using one person’s authentication token to a different person who is not authorized to view that content.**

* **Protected accounts:** A [protected account](https://help.x.com/safety-and-security/public-and-protected-posts)’s content is only available to people who have been approved by the owner to follow that account. So, if you run a service that accesses protected accounts, you may only do so to serve such content to the specific people with permission to view that content.
* **Blocked accounts:** People on X are able to [block](https://help.x.com/using-x/blocking-and-unblocking-accounts) access to their accounts for any reason they choose. Commingling information obtained from tokens (or any other API-based action) to bypass this choice is not permitted.

**As Direct Messages (DMs) are non-public in nature, services that provide DM features must take extra steps to safeguard personal privacy. You may not serve DM content to people who are not authorized to view that content. If your service provides DM functionality you must also:**

* Notify people if you send read receipt events for DMs. You can do this by providing a notice directly in your service, or by displaying read receipts from other participants in a conversation.
* Get consent before configuring media to be sent in a DM as "shared" (i.e. reusable across multiple DMs). If you do allow media in a DM to be “shared,” you must provide a clear notice that this content will be accessible to anyone with the media’s URL.

## Content compliance

**If you store X Content offline, you must keep it up to date with the current state of that content on X.** Specifically, you must delete or modify any content you have if it is deleted or modified on X. This must be done as soon as reasonably possible, or within 24 hours after receiving a request to do so by X or the applicable X account owner, or as otherwise required by your agreement with X or applicable law. This must be done unless otherwise prohibited by law, and only then with the express written permission of X.

Modified content can take various forms. This includes (but is not limited to):

* Content that has been made private or gained protected status
* Content that has been suspended from the platform
* Content that has had geotags removed from it
* Content that has been withheld or removed from X

## Off-X matching

**We limit the circumstances under which you may match a person on X to information obtained or stored off-X.** Off-X matching involves associating X Content, including a X @handle or user ID, with a person, household, device, browser, or other off-X identifier. You may only do this if you have express opt-in consent from the person before making the association, or as described below.

In situations in which you don’t have a person’s express, opt-in consent to link their X identity to an off-X identifier, we require that any connection you draw be based only on information that someone would reasonably expect to be used for that purpose. In addition, absent a person’s express opt-in consent you may only attempt to match your records about someone to a X identity based on:

* **Information provided directly to you by the person.** Note that records about individuals with whom you have no prior relationship, including data about individuals obtained from third parties, do not meet this standard; and/or
* **Public data.** “Public data” in this context refers to:
  * Information about a person that you obtained from a public, generally-available resource (such as a directory of members of a professional association)
  * Information on X about a person that is publicly available, including:
    * Posts
    * Profile information, including an account bio and publicly-stated location
    * Display name and @handle

## Your privacy policy

**You must display your service’s privacy policy to people before they are permitted to download, install, or sign up to your service.** It must disclose at least the following information:

* The information that you collect from people who use your service
* How you use and share that information (including with X)
* How people can contact you with inquiries and requests regarding their information

Your privacy policy must be consistent with all applicable laws, and be no less protective of people than [X’s Privacy Policy](https://x.com/privacy) and the [privacy policy of our other services and corporate affiliates](https://help.x.com/rules-and-policies/x-services-and-corporate-affiliates). You must cease your access to the X API and the use of all X Content if you are unable to comply with your and/or X’s Privacy Policy.

## Using geo-data

**Use of geo data comes with additional restrictions due to the sensitive nature of this information.** If your service adds location information to Posts, you must disclose to people:

* When you add location information
* Whether you add location information as a geotag or annotations data
* Whether your location information is listed as a place, or as geographic coordinates

If your application allows people to post with their location you must comply with X’s [geo guidelines](/developer-terms/geo-guidelines) in full.

**Any use of location data or geographic information on a standalone basis is prohibited.** You may not (and may not permit others to) store, aggregate, or cache location data and other geographic information contained in X Content, except as part of a Post. For example, you may not separate location data or geographic information out from Posts to show where individuals have been over time. Heat maps and related tools that show aggregated geo activity (e.g., the number of people in a city using a hashtag) are permitted.

## 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.


# X Developer PPU Agreement
Source: https://docs.x.com/developer-terms/ppu-agreement

The X Developer Pay-Per-Use Agreement covers terms for purchasing and using credits on paid X API services, including billing and usage rules.

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).

By accessing or using any Licensed Material (defined below), or clicking on a button to accept the terms of this Agreement or purchase credits for Paid Services, you agree to be bound by the terms of this Agreement. If you do not understand the terms herein or do not accept any part of them, then you may not use or access any Licensed Material. You may not use the Licensed Material or accept this Agreement if you are not of legal age to form a binding contract with X or if you are barred from using or receiving the Licensed Material under applicable law. To purchase and use a Paid Service you must: (i) be at least 18 years old or the age of majority as determined by the laws of the jurisdiction in which you live or (ii) have the express consent of your parent or guardian to purchase and use that Paid Service. If you are a parent or legal guardian and you allow your child (or a child that you are a guardian of) to purchase or use a Paid Service, you agree that the terms of this Agreement apply to you, you will abide by this Agreement, and you are responsible for the child’s activity on the Paid Services and for ensuring that the child also abides by the terms of this Agreement. In any case, as stated in the Who May Use the Services section of the [**X Terms of Service**](https://x.com/tos), you must be at least 13 years old to use the "Services" as defined in the X Terms of Service. If you are accepting this Agreement or using the Licensed Material on behalf of a company, organization, government, or other legal entity, you represent and warrant that you have the authority to bind such company, organization, government, or other legal entity to this Agreement, in which case the words “you” and “your” as used in this Agreement shall refer to such entity. If you do not agree to the terms of this Agreement, you may not (and you may not allow any of your personnel to) access or use the Licensed Material.

I. **Definitions**.

In this Agreement, the following definitions apply:

1. **“Credits”** means virtual units purchased by you to enable usage of Paid Services, with each API call or action deducting a specific number of Credits based on the Pricing Schedule. Credits are not refundable except as required by law, non-transferable, and do not expire unless otherwise specified.

2\. **“Developer Site”** means X’s developer site located at [**https://developer.x.com**](https://developer.x.com/)

3\. **“Direct Message”** means a private message that is sent on X Applications by one user to one or more other specific user(s) using X’s direct messaging function.

4\. **“Intellectual Property Rights”** means all copyrights, moral rights, patent rights, trademarks, and any other intellectual property or similar rights (registered or unregistered) throughout the world.

5\. **“Licensed Material”** means, individually or collectively, the X API and X Content.

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.

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://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.

12\. **“X API”** means X Application Programming Interfaces (each, an “API”), Software Development Kits (each, an “SDK”), and the related tools, documentation, data, technology, code, and other materials provided by X through the Developer Site.

13\. **“X Applications”** means X’s real-time information service, commonly referred to as “X,” which includes those services currently provided by X at its websites and X-owned, operated, or controlled mobile applications, social plug-ins, and application programming interfaces.

14\. **“X Content”** means Posts, the unique identification number generated for each Post, X end user profile information, and any other data and information made available to you through the X API or by any other means authorized by X, and any copies and derivative works thereof.

15\. **“X Marks”** means the X name, trademarks, and logos that X makes available to you, including via the Developer Site, solely for use in accordance with this Agreement.

16\. **“Users”** means visitors, users, or customers of your Services.

**II. X API and X Content.**

**A. License from X.** Subject to your compliance with the terms of this Agreement and the applicable Incorporated Developer Terms (as defined below), X hereby grants you a non-exclusive, royalty free, non-transferable, non-sublicensable, and revocable license to solely:

1\. Use the X API to integrate X Content into your Services or conduct analysis of the X Content, as explicitly approved by X;

2\. Copy a reasonable amount of and display the X Content on and through your Services to Users, as permitted by this Agreement;

3\. Modify X Content only to format it for display on your Services; and

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** 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://docs.x.com/developer-terms/policy);

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://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.**

**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).

**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://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.

**F. Use of X Marks.** You shall not include any of the X Marks in your registered corporate name(s), your logos, or your service or product names. You shall not create any derivative works of the X Marks or use the X Marks in a manner that creates or reasonably implies an endorsement, sponsorship, or association with X. All use of the X Marks and all goodwill arising out of the use will inure to X's benefit. You will not remove or alter any proprietary notices or X Marks on the Licensed Material.

**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.

**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 [**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.

**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).

**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.

**B. Removals.** If X Content is deleted, gains protected status, or is otherwise suspended, withheld, modified, or removed from the X Applications (including removal of location information), you will make all reasonable efforts to delete or modify that X Content (as applicable) as soon as possible, and in any case within twenty four (24) hours after a written request to do so by X or by an X user with regard to its X Content unless prohibited by law or regulation and with the express written permission of X.

**V. Ownership, Betas, and Feedback.**

**A. Ownership.** Except to the extent expressly stated otherwise in this Agreement, neither party will acquire any right, title, or interest in any Intellectual Property Rights owned or licensed by the other party. The Licensed Material is licensed, not sold, and X (or its licensors or X Application users, as applicable) retains and reserves all rights, including all Intellectual Property Rights, not expressly granted in this Agreement. You shall not do anything inconsistent with X’s ownership, including without limitation, challenging X’s ownership of the X Marks, challenging the validity of the licenses granted in this Agreement, or otherwise copying or exploiting the X Marks except as specifically authorized in this Agreement. If you acquire any rights in the X Marks or any confusingly similar marks, by operation of law or otherwise, you will, at no expense to X, immediately assign those rights to X.

**B. Betas.** X may provide you with early access to non-generally available alphas, betas, research studies, pilots, marketing services, or other programs from time to time (each, a “Beta”). Betas will be considered Confidential Information. Your participation in any Beta is at your own risk, may be subject to additional requirements, and may assist X in research, analyzing, and validating existing or prospective programs, products and/or tools.

**C. Feedback.** X will be free to use any feedback, comments, or suggestions you provide X related to X, the Licensed Material, Betas, or any other of X’s products or services (“Feedback”) in any way without any compensation or obligation to you or any third party and Feedback will be deemed Confidential Information. You hereby irrevocably assign to X all right, title, and interest to Feedback.

**VI. Confidentiality.**

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.**

**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://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.

**D. Usage Disputes**: If you believe there has been an error in credit deductions, you must notify X within thirty (30) days of the disputed deduction via [billing support](https://docs.x.com/forms/billing-support). X will investigate and, if an error is confirmed, adjust your credit balance accordingly. Adjustments are at X’s sole discretion and subject to this Agreement.

**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 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.

**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.

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.

**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.

**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.**

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.**

**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.

**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.**

**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.

**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.

**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.

**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.

**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.

**XIV. Miscellaneous.**

**A. Assignment.** You shall not assign any of the rights or obligations granted hereunder, in whole or in part, whether voluntarily or by operation of law, contract, merger (whether you are the surviving or disappearing entity), stock or asset sale, consolidation, dissolution, through government action, or otherwise, except with the prior written consent of X. X is authorized to sign modifications and consents for X Internet Unlimited Company, an Irish company responsible for the information of X users who live outside the United States. Any attempted assignment in violation of this Section will be null and void and X may terminate this Agreement.

**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 [**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.

**E. Data Protection Addendum.** Each party shall comply with the X Controller-to-Controller Data Protection Addendum located at [**https://gdpr.x.com/controller-to-controller-transfers.html**](https://gdpr.x.com/en/controller-to-controller-transfers.html), which may be updated by X from time to time.

**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.

[**DEVELOPER POLICY AND TERMS**](https://docs.x.com/developer-terms)

FOLLOW [**@XDEVELOPERS**](https://x.com/XDevelopers)

[**Subscribe to developer news**](https://developer.x.com/twitterdev-news-subscription)


# Display requirements: Replies
Source: https://docs.x.com/developer-terms/reply-requirements

Display requirements for showing replies to Posts in apps that use the X API, including thread structure, attribution, and reply context rules.

## Reply

Please follow the following guidelines for displaying replies.

### For a default reply:

<img alt="Post Reply" />

### For a reply with social context:

<img alt="Post Reply Social" />

### For a Quote:

<img alt="Post Reply Quote" />


# Restricted uses of the X API
Source: https://docs.x.com/developer-terms/restricted-use-cases

Details on restricted use cases for the X API, including off-platform tracking, government surveillance, sensitive data handling, and prohibited tools.

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.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.x.com/developer/en_us/topics/tips/2018/automation-and-the-use-of-multiple-accounts.html)

## Sensitive information

You should be careful about using X data to derive or infer potentially sensitive characteristics about X users. Never derive or infer, or store derived or inferred, information about a X user’s:

* Health (including 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
* Alleged or actual commission of a crime

Aggregate analysis of X content that does not store any personal data (for example, user IDs, usernames, and other identifiers) is permitted, provided that the analysis also complies with applicable laws and all parts of the Developer Agreement and Policy.

## Off-X matching

Off-X matching involves associating X content, including a X username or user ID, with a person, household, device, browser, or other off-X identifier. One example would be associating a X username with a business’s customer records (i.e. “John Doe” in your customer record is matched to @johndoe on X).

We want people to feel comfortable to create a separate and, if they choose, pseudonymous identity on X. If you intend to associate any information about a X user with an off-X identifier, we require that you get express, opt-in consent from the user before making the association. For example, you could get this consent if the user shares their X handle directly with you as part of a signup process for your service.

In situations in which you do not have a user’s express, opt-in consent to link their X identity to an off-X identifier, we require that any connection you draw be based only on information that a user would reasonably expect to be used for that purpose. If a user would be surprised to learn that you are using information they provided to link their X account to an identity off of X, don’t do it. In addition, absent a person’s express opt-in consent you may only attempt to match your records about someone to a X identity based on:

* **Information provided directly to you by the user.** Records about individuals with whom you have no prior relationship, including data about individuals obtained from third parties, do not meet this standard; and/or
* **Public data.** “Public data” in this context refers to:
  * Information about a user which you obtained from a public, generally-available resource (such as a directory of members of a professional association)
  * Information on X about a user which is publicly available, including:
    * Posts
    * Profile information, including a user’s bio and publicly-stated location
    * Display name and username

## Redistribution of X content

If you need to share X content you obtained via the X APIs with another party, the best way to do so is by sharing Post IDs, Direct Message IDs, and/or User IDs, which the end user of the content can then rehydrate (i.e. request the full Post, User, or Direct Message content) using the X APIs. This helps ensure that end users of X content always get the most current information directly from us.

We permit limited redistribution of hydrated X content via non-automated means. If you choose to share hydrated X content with another party in this way, you may only share up to 50,000 hydrated public Post Objects and/or User Objects per recipient, per day, and should not make this data publicly available (for example, as an attachment to a blog post or in a public Github repository).

There are a few other points to keep in mind about redistributing X content:

* You may only distribute up to a total of 1,500,000 Post IDs to a single entity within a 30 day period unless you’ve received prior express written permission from X.
* 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://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

You are not permitted to register multiple applications for a single use case, or substantially similar or overlapping use cases. Learn more about these policies [here](https://twittercommunity.com/t/policy-clarification-multiple-applications-for-the-same-use-case/92080).

In this context, we define “use case” as a consistent set of analyses, displays, or actions performed via an application. Providing the same service or application to different end users counts as a single use case: however, "white label" versions of a tool or service are not included. If you plan to "white label" versions of your application, you must notify and receive separate approval from us. These rules apply both to applications you register, and to applications registered by the end users of your tool or service; requiring your end users to register applications for the purpose of using your tool or service could result in enforcement actions against you, your applications, your customers, and/or the end users of your tool or service.

The only exception to this rule is to create development (“dev”), staging, and production (“prod”) instances of the same service. Ensure that these applications are clearly labeled (for instance, in the application name or description), and that you do not use development or staging applications for production purposes.

## Measuring the X service

Do not use the X APIs to measure the availability, performance, functionality, or usage of X for benchmarking or competitive purposes. For example, you should never use the X APIs to:

* 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.x.com/en/rules-and-policies/twitter-rules)

## Surveillance, privacy, and user protection

At X, protecting and defending the privacy of our users is built into the core DNA of our company — and our developer and data products reflect that commitment. We believe that X data can be a powerful force for good in the world — from saving lives during flooding in Jakarta to helping the USGS track earthquakes to working with the UN to achieve the Sustainable Development Goals. However, we prohibit the use of X data and the X APIs by any entity for surveillance purposes, or in any other way that would be inconsistent with our users' reasonable expectations of privacy. Period.

We describe prohibited uses of our data and developer products in the [Developer Agreement](/developer-terms/agreement), including prohibitions on investigating or tracking X users or their content, as well as tracking, alerting, or monitoring sensitive events (such as protests, rallies, or community organizing meetings).

Other categories of activities prohibited under these terms include (but are not limited to):

* Investigating or tracking sensitive groups and organizations, such as unions or activist groups
* Background checks or any form of extreme vetting
* Credit or insurance risk analyses
* Individual profiling or psychographic segmentation
* Facial recognition

These policies apply to all users of our APIs. Any misuse of the X APIs for these purposes will be subject to enforcement action, which can include suspension and termination of access.

For additional information for law enforcement authorities seeking information about X accounts, visit [https://t.co/le](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).


# About the Enterprise API — firehose, streams, and webhooks
Source: https://docs.x.com/enterprise-api/getting-started/about-x-api

Overview of the X Enterprise API, including full firehose access, volume and likes streams, account activity webhooks, custom rate limits, and support.

The Enterprise API provides the highest tier of access to X data. It includes everything available in the standard X API plus exclusive high-volume endpoints, semantic embedding operators for Filtered Stream, custom rate limits, and dedicated account management for organizations that need X data at scale.

***

## What you can do

Everything in the standard X API, plus:

| Capability                       | Description                                                                                                    |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------- |
| **Stream the full firehose**     | Access 100% of public posts in real-time with volume streams                                                   |
| **Stream all likes**             | Full and sampled likes streams in real-time                                                                    |
| **Advanced filtered streaming**  | Powerstream (low-latency keyword filtering)                                                                    |
| **Semantic embedding operators** | Match posts by meaning (not just keywords) using `embedding:` on Filtered Stream (Enterprise + Embedding tier) |
| **Deep engagement analytics**    | Post and media engagement metrics at scale                                                                     |
| **Account activity events**      | Real-time subscriptions for user events (posts, DMs, likes, follows)                                           |
| **Webhook delivery**             | Receive filtered stream data via webhooks                                                                      |
| **Custom rate limits**           | Elevated limits tailored to your throughput needs                                                              |
| **Dedicated support**            | Named account manager and priority issue resolution                                                            |

***

## Enterprise-exclusive endpoints

These endpoints are only available with Enterprise access:

<CardGroup>
  <Card title="Volume Streams" icon="satellite-dish" href="/x-api/posts/volume-streams/introduction">
    Full firehose and language-specific streams for complete real-time coverage.
  </Card>

  <Card title="Likes Streams" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-heart.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=3a435e6393c019d681c6f1a0737e21a8" href="/x-api/stream/likes-streams-introduction">
    Stream all likes or sampled likes across the platform.
  </Card>

  <Card title="Powerstream" icon="bolt" href="/x-api/powerstream/introduction">
    High-performance filtered streaming with advanced operators.
  </Card>

  <Card title="Engagement Metrics" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143" href="/x-api/posts/get-post-analytics">
    Post and media analytics for deep engagement insights.
  </Card>

  <Card title="Account Activity" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bell.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=5e0b3dcfbb39ba3d4619931d7cd927d1" href="/x-api/account-activity/introduction">
    Real-time event subscriptions for user activity.
  </Card>

  <Card title="Stream Webhooks" icon="webhook" href="/x-api/webhooks/stream/introduction">
    Filtered stream delivery via webhooks.
  </Card>
</CardGroup>

***

## All available resources

Enterprise access includes the full set of X API resources:

<CardGroup>
  <Card title="Posts" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f">
    Search, retrieve, create, and delete posts. Access timelines, threads, and quote posts.
  </Card>

  <Card title="Users" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305">
    Look up profiles, manage relationships, and access follower data.
  </Card>

  <Card title="Spaces" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-microphone.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=84616ff8f3d942047a71ee5e0a5adab9">
    Discover live audio conversations and participants.
  </Card>

  <Card title="Direct Messages" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-envelope.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=fbd38dbcd64d8688d3c9912ac30c4621">
    Send and receive private messages between users.
  </Card>

  <Card title="Lists" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5">
    Create and manage curated lists of accounts.
  </Card>

  <Card title="Trends" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-feather-chart-line.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=185e7e1271f798947403bb3f0c44f294">
    Access trending topics by location.
  </Card>
</CardGroup>

***

## API highlights

<Accordion title="Fields and expansions">
  Request only the data you need. Use `fields` parameters to select specific attributes and `expansions` to include related objects.

  ```bash theme={null}
  curl "https://api.x.com/2/tweets/123?tweet.fields=created_at,public_metrics&expansions=author_id&user.fields=username" \
    -H "Authorization: Bearer $TOKEN"
  ```

  [Learn more about fields →](/x-api/fundamentals/fields)
</Accordion>

<Accordion title="Post annotations">
  Posts include semantic annotations identifying people, places, products, and topics. Filter streams and searches by topic.

  [Learn more about annotations →](/x-api/fundamentals/post-annotations)
</Accordion>

<Accordion title="Engagement metrics">
  Enterprise customers get access to dedicated engagement metrics endpoints for both posts and media, providing deep analytics at scale beyond what standard public metrics offer.

  [Learn more about metrics →](/x-api/fundamentals/metrics)
</Accordion>

<Accordion title="Conversation tracking">
  Reconstruct entire conversation threads using `conversation_id`. Track replies across the full thread.

  [Learn more about conversation tracking →](/x-api/fundamentals/conversation-id)
</Accordion>

<Accordion title="Edit history">
  Access the edit history of posts, including all previous versions and edit metadata.

  [Learn more about edit posts →](/x-api/fundamentals/edit-posts)
</Accordion>

***

## Pricing

Enterprise plans are custom-tailored to your organization's needs. Pricing is based on your data volume, endpoint usage, and support requirements.

| Feature                   | Details                                             |
| :------------------------ | :-------------------------------------------------- |
| **Custom packages**       | Tailored to your specific data and throughput needs |
| **Longer-term contracts** | Predictable pricing with committed usage agreements |
| **No post read cap**      | Custom or unlimited post read volumes               |
| **Dedicated support**     | Included with all Enterprise plans                  |

[Contact sales for pricing](/forms/enterprise-api-interest)

***

## Next steps

<CardGroup>
  <Card title="Apply for access" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/forms/enterprise-api-interest">
    Contact our sales team to discuss your needs.
  </Card>

  <Card title="Explore endpoints" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/create-post">
    Browse all available endpoints including Enterprise-exclusive ones.
  </Card>
</CardGroup>


# Getting enterprise access
Source: https://docs.x.com/enterprise-api/getting-started/getting-access

Apply for X Enterprise API access, work with your dedicated account team during onboarding, and get credentials configured for your data volume.

Enterprise access requires an application and onboarding process. Your dedicated account team will help you get set up with credentials and configure your access.

<Button href="/forms/enterprise-api-interest">Apply for Enterprise access</Button>

***

## Step 1: Apply for enterprise access

<Steps>
  <Step title="Submit an application">
    [Fill out the Enterprise interest form](/forms/enterprise-api-interest) with details about your organization and use case.
  </Step>

  <Step title="Discuss your needs">
    Our sales team will reach out to understand your data volume, endpoint requirements, and support needs.
  </Step>

  <Step title="Get a custom package">
    Receive a tailored plan with pricing, rate limits, and access levels designed for your use case.
  </Step>
</Steps>

***

## Step 2: Get onboarded

Once your Enterprise plan is in place, your dedicated account manager will help you set up:

<Steps>
  <Step title="Create your developer app">
    Set up your app in the [Developer Console](https://console.x.com) with Enterprise-level access.
  </Step>

  <Step title="Configure your access">
    Your account manager will help configure rate limits, endpoint access, and any custom settings.
  </Step>

  <Step title="Generate credentials">
    Generate your API keys and tokens for authentication.
  </Step>
</Steps>

***

## Step 3: Save your credentials

You'll receive several credentials depending on your authentication needs:

| Credential                | Purpose                                                                  |
| :------------------------ | :----------------------------------------------------------------------- |
| **API Key & Secret**      | Identify your app. Used to generate tokens and sign OAuth 1.0a requests. |
| **Bearer Token**          | App-only authentication for reading public data.                         |
| **Access Token & Secret** | Make requests on behalf of your own account (OAuth 1.0a).                |
| **Client ID & Secret**    | OAuth 2.0 authentication for user-context requests.                      |

<Warning>
  **Save immediately.** X only displays credentials once. Store them in a password manager or secure vault. If you lose them, regenerate them (which invalidates the old ones).
</Warning>

***

## Which credentials do you need?

<Tabs>
  <Tab title="Reading public data">
    Use the **Bearer Token** for simple, read-only access to public data.

    ```bash theme={null}
    curl "https://api.x.com/2/users/by/username/xdevelopers" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```

    Best for: Searching posts, looking up users, reading trends.
  </Tab>

  <Tab title="Acting as a user">
    Use **OAuth 2.0** (recommended) or **OAuth 1.0a** to act on behalf of users.

    OAuth 2.0 offers fine-grained scopes—request only the permissions you need.

    Best for: Posting, liking, following, accessing DMs.

    [OAuth 2.0 guide →](/resources/fundamentals/authentication/oauth-2-0/overview)
  </Tab>

  <Tab title="Acting as yourself">
    Use your **Access Token & Secret** to make requests as your own account.

    These tokens represent the account that owns the app.

    Best for: Testing, personal bots, your own automation.
  </Tab>
</Tabs>

***

## Credential security best practices

<CardGroup>
  <Card title="Use environment variables" icon="terminal">
    Never hardcode credentials in your source code.
  </Card>

  <Card title="Don't commit to git" icon="code-branch">
    Add credential files to `.gitignore`.
  </Card>

  <Card title="Rotate regularly" icon="arrows-rotate">
    Regenerate credentials periodically as a security measure.
  </Card>

  <Card title="Use minimal scopes" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-check.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=768533bde161ac68862de87449f011c3">
    Only request the OAuth permissions your app needs.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="Make your first request" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/getting-started/make-your-first-request">
    Call the API with your new credentials.
  </Card>

  <Card title="Learn about authentication" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/resources/fundamentals/authentication/overview">
    Understand OAuth 1.0a and OAuth 2.0.
  </Card>
</CardGroup>


# Important resources for Enterprise API customers
Source: https://docs.x.com/enterprise-api/getting-started/important-resources

Essential resources for X Enterprise API customers, including onboarding guides, account managers, support contacts, status pages, and SDKs.

Bookmark these essential resources for X API development.

***

## Documentation

<CardGroup>
  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/introduction">
    Complete endpoint documentation with parameters and examples.
  </Card>

  <Card title="Data Dictionary" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/fundamentals/data-dictionary">
    Object schemas for posts, users, media, and more.
  </Card>

  <Card title="Authentication" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/resources/fundamentals/authentication/overview">
    OAuth 1.0a and OAuth 2.0 implementation guides.
  </Card>

  <Card title="Rate Limits" icon="gauge-high" href="/x-api/fundamentals/rate-limits">
    Per-endpoint limits and best practices.
  </Card>
</CardGroup>

***

## Tools

| Tool                                                                                                                                         | Description                           |
| :------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |
| [Developer Console](https://console.x.com)                                                                                                   | Manage apps, credentials, and billing |
| [Postman Collection](https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80) | Interactive API testing               |
| [Python SDK](/xdks/python/overview)                                                                                                          | Official Python library               |
| [TypeScript SDK](/xdks/typescript/overview)                                                                                                  | Official TypeScript library           |
| [OpenAPI Spec](https://api.x.com/2/openapi.json)                                                                                             | Machine-readable API specification    |

***

## Learning

<CardGroup>
  <Card title="Tutorials" icon="graduation-cap" href="/tutorials">
    Step-by-step guides for common use cases.
  </Card>

  <Card title="Sample Code" icon="github" href="https://github.com/xdevplatform">
    Example apps and code samples.
  </Card>

  <Card title="What to Build" icon="lightbulb" href="/x-api/what-to-build">
    Ideas and inspiration for projects.
  </Card>

  <Card title="Migration Guide" icon="route" href="/x-api/migrate/overview">
    Upgrade from v1.1 to v2.
  </Card>
</CardGroup>

***

## Community and support

<CardGroup>
  <Card title="Developer Forum" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=ce6313d8c0b7b4e5363f2ce80b89f7e4" href="https://devcommunity.x.com">
    Ask questions and share solutions with the community.
  </Card>

  <Card title="Support Hub" icon="circle-question" href="https://developer.x.com/en/support">
    FAQs, troubleshooting, and contact options.
  </Card>

  <Card title="@XDevelopers" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-logo-x.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=53e3153f3b8d6efdad31484ef133b274" href="https://x.com/XDevelopers">
    Official updates and announcements.
  </Card>

  <Card title="@API" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-logo-x.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=53e3153f3b8d6efdad31484ef133b274" href="https://x.com/api">
    API-specific news and tips.
  </Card>
</CardGroup>

***

## Stay updated

| Resource                                                             | What you'll get                      |
| :------------------------------------------------------------------- | :----------------------------------- |
| [Changelog](/changelog)                                              | All platform changes and updates     |
| [Newsletter](/newsletter)                                            | Monthly roundup of news and features |
| [Forum Announcements](https://devcommunity.x.com/c/announcements/22) | Important platform notices           |
| [API Status](https://developer.x.com/status)                         | Real-time service availability       |

<Tip>
  Follow [@XDevelopers](https://x.com/XDevelopers) and turn on notifications to catch breaking changes and new features.
</Tip>

***

## Quick reference

### Response structure

All v2 responses follow this structure:

```json theme={null}
{
  "data": { ... },      // Primary object(s)
  "includes": { ... },  // Expanded objects (if requested)
  "meta": { ... },      // Pagination info
  "errors": [ ... ]     // Partial errors (if any)
}
```

### Common parameters

| Parameter          | Use                          |
| :----------------- | :--------------------------- |
| `tweet.fields`     | Request specific post fields |
| `user.fields`      | Request specific user fields |
| `expansions`       | Include related objects      |
| `max_results`      | Limit results per page       |
| `pagination_token` | Get next/previous page       |

### Authentication methods

| Method       | Use case                                |
| :----------- | :-------------------------------------- |
| Bearer Token | Read-only public data                   |
| OAuth 2.0    | User actions with fine-grained scopes   |
| OAuth 1.0a   | User actions (legacy, full permissions) |

[Full authentication guide →](/resources/fundamentals/authentication/overview)


# Make your first Enterprise API request
Source: https://docs.x.com/enterprise-api/getting-started/make-your-first-request

Make your first X Enterprise API request, including authentication setup, endpoint selection, sample cURL commands, and response handling tips.

This guide walks you through making your first X API request. You'll need a [developer account with app credentials](/x-api/getting-started/getting-access) before starting.

***

## Quick start with cURL

The fastest way to test the API is with cURL. Let's look up a user:

```bash theme={null}
curl "https://api.x.com/2/users/by/username/xdevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

Replace `$BEARER_TOKEN` with your actual Bearer Token. You'll get a response like:

```json theme={null}
{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "xdevelopers"
  }
}
```

***

## Step-by-step guide

<Steps>
  <Step title="Get your Bearer Token">
    In the [Developer Console](https://console.x.com), navigate to your app and copy the Bearer Token.
  </Step>

  <Step title="Choose an endpoint">
    Start with one of these beginner-friendly endpoints:

    | Endpoint                                          | What it does                       |
    | :------------------------------------------------ | :--------------------------------- |
    | [User lookup](/x-api/users/lookup/introduction)   | Get user profile by username or ID |
    | [Post lookup](/x-api/posts/lookup/introduction)   | Get post by ID                     |
    | [Recent search](/x-api/posts/search/introduction) | Search posts from the last 7 days  |
  </Step>

  <Step title="Make the request">
    Use cURL, Postman, or your preferred HTTP client:

    ```bash theme={null}
    # Look up a user by username
    curl "https://api.x.com/2/users/by/username/xdevelopers" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```
  </Step>

  <Step title="Parse the response">
    Responses are JSON. The primary data is in the `data` field:

    ```json theme={null}
    {
      "data": {
        "id": "2244994945",
        "name": "X Developers",
        "username": "xdevelopers"
      }
    }
    ```
  </Step>
</Steps>

***

## Request more data with fields

By default, endpoints return minimal fields. Use the `fields` parameter to request additional data:

```bash theme={null}
curl "https://api.x.com/2/users/by/username/xdevelopers?user.fields=created_at,description,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

Response:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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
    }
  }
}
```

[Learn more about fields →](/x-api/fundamentals/fields)

***

## More examples

<Tabs>
  <Tab title="Look up a post">
    ```bash theme={null}
    curl "https://api.x.com/2/tweets/1460323737035677698?tweet.fields=created_at,public_metrics" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```
  </Tab>

  <Tab title="Search recent posts">
    ```bash theme={null}
    curl "https://api.x.com/2/tweets/search/recent?query=from:xdevelopers&tweet.fields=created_at" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```
  </Tab>

  <Tab title="Get user's posts">
    ```bash theme={null}
    curl "https://api.x.com/2/users/2244994945/tweets?max_results=5" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```
  </Tab>
</Tabs>

***

## Using code instead of cURL

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import requests

    bearer_token = "YOUR_BEARER_TOKEN"
    url = "https://api.x.com/2/users/by/username/xdevelopers"

    headers = {"Authorization": f"Bearer {bearer_token}"}
    response = requests.get(url, headers=headers)

    print(response.json())
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const bearerToken = "YOUR_BEARER_TOKEN";
    const url = "https://api.x.com/2/users/by/username/xdevelopers";

    fetch(url, {
      headers: { Authorization: `Bearer ${bearerToken}` }
    })
      .then(res => res.json())
      .then(data => console.log(data));
    ```
  </Tab>

  <Tab title="Official SDKs">
    For production use, we recommend the official SDKs:

    * [Python SDK](/xdks/python/overview)
    * [TypeScript SDK](/xdks/typescript/overview)

    They handle authentication, pagination, and rate limiting automatically.
  </Tab>
</Tabs>

***

## Tools for testing

<CardGroup>
  <Card title="Postman" icon="server" href="/tutorials/postman-getting-started">
    Visual API testing with our collection.
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Examples in multiple languages.
  </Card>

  <Card title="API reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/lookup/introduction">
    Full endpoint documentation.
  </Card>
</CardGroup>

***

## Troubleshooting

<Accordion title="401 Unauthorized">
  * Check that your Bearer Token is correct
  * Ensure the token hasn't been regenerated
  * Verify the `Authorization` header format: `Bearer YOUR_TOKEN`
</Accordion>

<Accordion title="403 Forbidden">
  * Your app may not have access to this endpoint
  * Some endpoints require user-context authentication (OAuth 1.0a or 2.0)
  * Check your app's permissions in the Developer Console
</Accordion>

<Accordion title="429 Too Many Requests">
  * You've hit a rate limit
  * Check the `x-rate-limit-reset` header for when to retry
  * Implement exponential backoff in your code
</Accordion>

[Full error reference →](/x-api/fundamentals/response-codes-and-errors)

***

## Next steps

<CardGroup>
  <Card title="Learn authentication" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/resources/fundamentals/authentication/overview">
    Understand OAuth for user-context requests.
  </Card>

  <Card title="Explore endpoints" icon="compass" href="/x-api/posts/search/introduction">
    Discover what you can build.
  </Card>

  <Card title="Use an SDK" icon="cube" href="/tools-and-libraries">
    Faster development with official libraries.
  </Card>

  <Card title="Build something" icon="hammer" href="/x-api/what-to-build">
    Ideas for what to create.
  </Card>
</CardGroup>


# Enterprise API pricing and custom plans
Source: https://docs.x.com/enterprise-api/getting-started/pricing

Enterprise API plans are custom-tailored to your organization's data volume, endpoint usage, and support needs. Contact sales for high-volume pricing.

Enterprise plans are custom-tailored to your organization's needs. Work with a dedicated account team to build a package that matches your data volume, endpoint usage, and support requirements.

<Button href="/forms/enterprise-api-interest">Contact sales for pricing</Button>

***

## How Enterprise pricing works

<CardGroup>
  <Card title="Custom packages" icon="sliders">
    Pricing is tailored to your specific data volume, endpoint needs, and throughput requirements.
  </Card>

  <Card title="Committed contracts" icon="file-contract">
    Predictable costs with longer-term agreements and committed usage levels.
  </Card>

  <Card title="No post read cap" icon="infinity">
    Custom or unlimited post read volumes, far beyond the 3 million monthly cap on pay-per-use plans.
  </Card>

  <Card title="Dedicated support included" icon="headset">
    A named account manager and priority technical support are included with every Enterprise plan.
  </Card>
</CardGroup>

***

## What's included

Every Enterprise plan includes access to the full X API plus exclusive Enterprise endpoints:

| Feature                          | Details                                                                                       |
| :------------------------------- | :-------------------------------------------------------------------------------------------- |
| **All standard endpoints**       | Everything available in the pay-per-use X API                                                 |
| **Volume streams**               | Full firehose and language-specific streams                                                   |
| **Likes streams**                | Full and sampled likes in real-time                                                           |
| **Powerstream**                  | Advanced filtered streaming                                                                   |
| **Semantic embedding operators** | `embedding:` operator for semantic matching in Filtered Stream only (requires Embedding tier) |
| **Engagement metrics**           | Post and media analytics endpoints                                                            |
| **Account Activity**             | Real-time user event subscriptions                                                            |
| **Stream webhooks**              | Filtered stream delivery via webhooks                                                         |
| **Custom rate limits**           | Elevated limits tailored to your needs                                                        |
| **Dedicated support**            | Named account manager and priority resolution                                                 |

***

## Enterprise vs. pay-per-use

|                                  | Pay-per-use                 | Enterprise                                                               |
| :------------------------------- | :-------------------------- | :----------------------------------------------------------------------- |
| **Pricing model**                | Credit-based, pay as you go | Custom contract                                                          |
| **Monthly post cap**             | 3 million reads             | Custom / unlimited                                                       |
| **Volume streams**               | Not available               | Full firehose and language streams                                       |
| **Likes streams**                | Not available               | Full and sampled likes                                                   |
| **Semantic embedding operators** | Not available               | `embedding:` operator for Filtered Stream only (requires Embedding tier) |
| **Engagement metrics**           | Not available               | Post and media analytics                                                 |
| **Rate limits**                  | Standard                    | Custom / elevated                                                        |
| **Support**                      | Community forum             | Dedicated account manager                                                |
| **Commitment**                   | None                        | Contract-based                                                           |

***

## Monitoring usage

Track your API usage programmatically with the [Usage endpoint](/x-api/usage/introduction):

```bash theme={null}
curl "https://api.x.com/2/usage/tweets" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

This returns daily Post consumption counts, helping you:

* Track consumption against your contract limits
* Generate usage reports for stakeholders
* Identify high-consumption endpoints
* Plan capacity with your account team

***

## Get started

<Steps>
  <Step title="Contact sales">
    [Apply for Enterprise access](/forms/enterprise-api-interest) and tell us about your use case and data needs.
  </Step>

  <Step title="Get a custom quote">
    Our sales team will work with you to build a package that fits your requirements and budget.
  </Step>

  <Step title="Get onboarded">
    Your dedicated account manager will help you set up credentials, configure access, and start building.
  </Step>
</Steps>

<Button href="/forms/enterprise-api-interest">Apply for Enterprise access</Button>

***

## Next steps

<CardGroup>
  <Card title="Apply for access" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/forms/enterprise-api-interest">
    Contact our sales team to get started.
  </Card>

  <Card title="Usage API" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143" href="/x-api/usage/introduction">
    Monitor usage programmatically.
  </Card>
</CardGroup>


# X Enterprise API introduction and product overview
Source: https://docs.x.com/enterprise-api/introduction

Enterprise-grade access to the X firehose, volume streams, full-archive search, and PowerTrack with dedicated technical support and custom pricing.

The X API Enterprise plan provides the highest level of access to X data. Get complete firehose coverage, volume streams, semantic embedding operators for Filtered Stream, dedicated account management, and custom rate limits designed for organizations that depend on X data at scale.

<CardGroup>
  <Card title="Request access" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/forms/enterprise-api-interest">
    Apply for Enterprise access with a dedicated account team.
  </Card>

  <Card title="API reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/create-post">
    Explore all available endpoints, including Enterprise-exclusive ones.
  </Card>

  <Card title="SDKs" icon="cube" href="/tools-and-libraries">
    Official Python and TypeScript libraries.
  </Card>
</CardGroup>

***

## Why Enterprise?

Enterprise access includes everything in the pay-per-use X API plus exclusive high-volume endpoints, dedicated support, and custom packages tailored to your needs.

<CardGroup>
  <Card title="Complete firehose access" icon="fire">
    Stream 100% of public posts in real-time. No sampling, no limits. Get every post as it happens.
  </Card>

  <Card title="Volume streams" icon="wave-pulse">
    Access full-volume and language-specific streams, including English, Japanese, Korean, and Portuguese firehoses.
  </Card>

  <Card title="Dedicated support" icon="headset">
    Get a dedicated account manager, personalized technical support, and priority issue resolution.
  </Card>

  <Card title="Custom rate limits" icon="gauge-high">
    Higher rate limits and custom-tailored packages to match your throughput requirements.
  </Card>

  <Card title="Engagement metrics at scale" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143">
    Access post and media analytics endpoints for deep engagement insights across large datasets.
  </Card>

  <Card title="Compliance streams" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-check.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=768533bde161ac68862de87449f011c3">
    Stay compliant with real-time compliance event streams for posts, users, and likes.
  </Card>

  <Card title="Semantic embedding for Filtered Stream" icon="brain">
    Match posts by conceptual meaning — not just keywords — using the `embedding:` operator in Filtered Stream (requires Embedding tier).
  </Card>
</CardGroup>

***

## Enterprise-exclusive endpoints

These endpoints are only available on Enterprise plans:

<CardGroup>
  <Card title="Volume Streams" icon="satellite-dish" href="/x-api/posts/volume-streams/introduction">
    Full firehose, language-specific streams, and sampled streams.
  </Card>

  <Card title="Likes Streams" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-heart.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=3a435e6393c019d681c6f1a0737e21a8" href="/x-api/stream/likes-streams-introduction">
    Stream all likes or sampled likes in real-time.
  </Card>

  <Card title="Powerstream" icon="bolt" href="/x-api/powerstream/introduction">
    High-performance filtered streaming with low latency (keyword operators).
  </Card>

  <Card title="Engagement Metrics" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143" href="/x-api/posts/get-post-analytics">
    Deep analytics for post and media engagement.
  </Card>

  <Card title="Account Activity" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bell.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=5e0b3dcfbb39ba3d4619931d7cd927d1" href="/x-api/account-activity/introduction">
    Subscribe to real-time user activity events including posts, DMs, likes, and follows.
  </Card>

  <Card title="Stream Webhooks" icon="webhook" href="/x-api/webhooks/stream/introduction">
    Receive filtered stream data via webhooks instead of persistent connections.
  </Card>
</CardGroup>

***

## What you can build

Enterprise access powers the most demanding use cases on X.

<CardGroup>
  <Card title="Posts" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f" href="/x-api/posts/lookup/introduction">
    Search, retrieve, and publish posts. Access timelines, threads, and quote posts.
  </Card>

  <Card title="Users" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305" href="/x-api/users/lookup/introduction">
    Look up users, manage follows, blocks, and mutes.
  </Card>

  <Card title="Spaces" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-microphone.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=84616ff8f3d942047a71ee5e0a5adab9" href="/x-api/spaces/lookup/introduction">
    Find live audio conversations and their participants.
  </Card>

  <Card title="Direct Messages" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-envelope.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=fbd38dbcd64d8688d3c9912ac30c4621" href="/x-api/direct-messages/lookup/introduction">
    Send and receive private messages.
  </Card>

  <Card title="Lists" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/lists/list-lookup/introduction">
    Create and manage curated lists of accounts.
  </Card>

  <Card title="Trends" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-feather-chart-line.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=185e7e1271f798947403bb3f0c44f294" href="/x-api/trends/trends-by-woeid/introduction">
    Access trending topics by location.
  </Card>
</CardGroup>

***

## Key features

<Tabs>
  <Tab title="Full firehose">
    ### Complete real-time coverage

    Stream 100% of public posts as they happen. No sampling, no gaps. Enterprise firehose access gives you the complete picture of public conversation on X.

    Available streams:

    * **All posts** - Every public post in real-time
    * **English posts** - All English-language posts
    * **Japanese posts** - All Japanese-language posts
    * **Korean posts** - All Korean-language posts
    * **Portuguese posts** - All Portuguese-language posts
    * **Sampled streams** - 1% and 10% random samples

    [Learn more about volume streams](/x-api/posts/volume-streams/introduction)
  </Tab>

  <Tab title="Data access">
    ### Rich data objects

    Access detailed, structured data for posts, users, media, and more:

    * **Posts**: Full text, metrics, entities, annotations, conversation threads
    * **Users**: Profiles, follower counts, verification status
    * **Media**: Images, videos, GIFs with metadata
    * **Polls**: Options and vote counts

    Customize responses with [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) to get exactly the data you need.
  </Tab>

  <Tab title="Streaming">
    ### Filtered stream

    Get posts delivered in real-time as they're published. Enterprise adds higher rule limits and the semantic `embedding:` operator (in Filtered Stream only) to match posts by meaning (not just keywords).

    ```bash theme={null}
    # Add a rule
    curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
      -H "Authorization: Bearer $TOKEN" \
      -d '{"add": [{"value": "from:xdevelopers"}]}'

    # Connect to stream
    curl "https://api.x.com/2/tweets/search/stream" \
      -H "Authorization: Bearer $TOKEN"
    ```

    [Learn more about filtered stream](/x-api/posts/filtered-stream/introduction)
  </Tab>

  <Tab title="Search & analytics">
    ### Full-archive search

    Search the complete history of public posts back to 2006. Build queries with operators for users, keywords, dates, and more.

    ```bash theme={null}
    curl "https://api.x.com/2/tweets/search/all?query=AI%20lang:en" \
      -H "Authorization: Bearer $TOKEN"
    ```

    ### Engagement metrics

    Access deep engagement analytics including impressions, likes, reposts, replies, video views, and media-level metrics.

    [Learn more about search](/x-api/posts/search/introduction)
  </Tab>
</Tabs>

***

## Enterprise vs. pay-per-use

| Feature                | Pay-per-use             | Enterprise                                                            |
| :--------------------- | :---------------------- | :-------------------------------------------------------------------- |
| **Post search**        | Recent and full-archive | Recent and full-archive                                               |
| **Filtered stream**    | Up to 1,000 rules       | 5,000+ rules + semantic `embedding:` operators (Filtered Stream only) |
| **Volume streams**     | -                       | Full firehose and language streams                                    |
| **Likes streams**      | -                       | Full and sampled likes                                                |
| **Powerstream**        | -                       | Advanced filtered streaming                                           |
| **Engagement metrics** | -                       | Post and media analytics                                              |
| **Account Activity**   | -                       | Real-time user event subscriptions                                    |
| **Monthly post cap**   | 3 million reads         | Custom / unlimited                                                    |
| **Rate limits**        | Standard                | Custom / elevated                                                     |
| **Support**            | Community forum         | Dedicated account manager                                             |

***

## Get started

<Steps>
  <Step title="Apply for Enterprise access">
    [Contact our sales team](/forms/enterprise-api-interest) to discuss your needs and get a custom package.
  </Step>

  <Step title="Get onboarded">
    Your dedicated account manager will help you set up credentials and configure your access.
  </Step>

  <Step title="Start building">
    Use the same modern v2 API endpoints plus Enterprise-exclusive endpoints for your integration.

    ```bash theme={null}
    curl "https://api.x.com/2/users/by/username/xdevelopers" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```
  </Step>
</Steps>

<Button href="/forms/enterprise-api-interest">Apply for Enterprise access</Button>

***

## Tools & libraries

<CardGroup>
  <Card title="Python SDK" icon="python" href="/xdks/python/overview">
    Official Python library with async support.
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/xdks/typescript/overview">
    Official TypeScript/JavaScript library.
  </Card>

  <Card title="Postman" icon="server" href="https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80">
    Interactive API explorer.
  </Card>
</CardGroup>

[Browse all libraries](/tools-and-libraries)

***

## Support

<CardGroup>
  <Card title="Dedicated Account Manager" icon="headset">
    Enterprise customers get a dedicated point of contact for technical and account support.
  </Card>

  <Card title="Developer Forum" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=ce6313d8c0b7b4e5363f2ce80b89f7e4" href="https://devcommunity.x.com">
    Get help from the community and X team.
  </Card>
</CardGroup>


# Enterprise data customers
Source: https://docs.x.com/enterprise/customer-directory

Directory of enterprise customers using the X API for social listening, research, financial analysis, public safety, brand monitoring, and other use cases.

## Discover companies that use X data to help power innovation

Our enterprise data customers receive commercial-level access to APIs and dedicated account and developer support. Apply for enterprise API access to get the highest level of access and reliability.

[Apply for enterprise access →](/forms/enterprise-api-interest)

## X Official Partners

Work with a trusted X Official Partner to expand what's possible for your business. Each Official Partner has been selected for the program after an extensive evaluation, and represents excellence, value, and trust.

[Check our partners →](https://partners.x.com/en)

## Enterprise customers listing

<Tabs>
  <Tab title="A-E">
    <CardGroup>
      <LogoCard title="Agility PR Solutions" href="https://www.agilitypr.com/" />

      <LogoCard title="Agorapulse" href="https://www.agorapulse.com/?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Alethea" href="https://www.alethea.com/?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Allied Architects, Inc." href="https://www.aainc.co.jp/" />

      <LogoCard title="Altmetric" href="http://altmetric.com" />

      <LogoCard title="Audiense" href="https://audiense.com/" />

      <LogoCard title="Avaya LLC" href="https://www.avaya.com" />

      <LogoCard title="Ayrshare" href="https://www.ayrshare.com/" />

      <LogoCard title="Blinkfire Analytics" href="https://www.blinkfire.com/" />

      <LogoCard title="Blue Robot" href="https://www.bluerobot.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="BoomSonar" href="https://www.boomsonar.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Brandwatch" href="https://partners.x.com/en/partners/brandwatch" />

      <LogoCard title="Brand24" href="https://brand24.com/" />

      <LogoCard title="Buffer" href="https://buffer.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Buzzmonitor" href="https://buzzmonitor.com/" />

      <LogoCard title="Canvs AI" href="https://canvs.ai/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Circleboom" href="https://circleboom.com/" />

      <LogoCard title="Cision" href="https://www.cision.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Civic Plus" href="https://www.civicplus.com/social-media-archiving/" />

      <LogoCard title="comScore, Inc." href="https://www.comscore.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Context Analytics, Inc." href="https://www.contextanalytics-ai.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Coosto" href="http://www.coosto.com?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Crisp" href="https://www.crispthinking.com/?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Cubic Inc." href="https://www.cubic-corp.co.jp" />

      <LogoCard title="Dash Hudson" href="https://www.dashhudson.com/" />

      <LogoCard title="DataEQ" href="https://dataeq.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Dataminr" href="https://partners.x.com/en/partners/dataminr" />

      <LogoCard title="Determ" href="https://www.determ.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Digital Shadows" href="https://www.digitalshadows.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Emplifi" href="https://emplifi.io/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Eyesover Technologies" href="https://www.eyesover.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />
    </CardGroup>
  </Tab>

  <Tab title="F-K">
    <CardGroup>
      <LogoCard title="Facelift" href="https://facelift-bbt.com/en/" />

      <LogoCard title="Factal" href="https://www.factal.com/?utm_source=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Fedica" href="https://fedica.com" />

      <LogoCard title="Fizziology" href="https://fizziology.com/?utm_source=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Freshworks" href="https://www.freshworks.com/" />

      <LogoCard title="Genesys" href="https://www.genesys.com" />

      <LogoCard title="Guud" href="https://www.guud.tv/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Hootsuite" href="https://hootsuite.com/" />

      <LogoCard title="Hypefury" href="https://hypefury.com" />

      <LogoCard title="IC Group" href="https://www.icgroupinc.com/?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="IFTTT" href="https://ifttt.com/?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Intrado" href="https://developer.x.com/content/dam/developer-twitter/enterprise-directory/Intrado.png" />

      <LogoCard title="Kaito AI" href="https://www.kaito.ai/" />

      <LogoCard title="Keyhole" href="https://keyhole.co/" />

      <LogoCard title="Konnect Insights" href="https://konnectinsights.com/?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Kore" href="https://koresoftware.com" />
    </CardGroup>
  </Tab>

  <Tab title="L-O">
    <CardGroup>
      <LogoCard title="LexisNexis" href="https://www.lexisnexis.com/" />

      <LogoCard title="LifeRaft" href="http://liferaftlabs.com" />

      <LogoCard title="ListenFirst" href="https://www.listenfirstmedia.com/" />

      <LogoCard title="LivePerson" href="https://www.liveperson.com/?utm_source=twitter_data_website&utm_medium=twitter%20enterprise%20customer%20directory&utm_campaign=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Locobuzz Solutions Pvt Ltd." href="https://locobuzz.com/" />

      <LogoCard title="Lucidya" href="https://lucidya.com" />

      <LogoCard title="Marfeel" href="http://www.marfeel.com" />

      <LogoCard title="MarketCast" href="http://www.marketcast.com" />

      <LogoCard title="Market Prophit" href="http://www.marketprophit.com" />

      <LogoCard title="Meltwater" href="http://www.meltwater.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Metricool" href="https://metricool.com" />

      <LogoCard title="Nielsen Sports" href="https://www.nielsensports.com/" />

      <LogoCard title="NetBase" href="https://www.netbase.com/" />

      <LogoCard title="Notified" href="https://www.notified.com/?utm_source=twitter_data_website&utm_medium=twitter%20enterprise%20customer%20directory&utm_campaign=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="NTT DATA Corporation" href="https://partners.x.com/en/partners/ntt-data" />

      <LogoCard title="OBI4wan" href="https://www.obi4wan.com/nl/?utm_source=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Oktopost" href="https://www.oktopost.com/" />

      <LogoCard title="Ontic" href="https://ontic.co/?utm_source=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Orlo" href="https://orlo.tech/" />
    </CardGroup>
  </Tab>

  <Tab title="P-Z">
    <CardGroup>
      <LogoCard title="PeakMetrics" href="https://www.peakmetrics.com/" />

      <LogoCard title="Pickles Inc." href="https://pickles.tv" />

      <LogoCard title="Publer" href="https://publer.io" />

      <LogoCard title="PublicSonar" href="https://publicsonar.com/?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Pulsar" href="https://www.pulsarplatform.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Qualtrics" href="https://www.qualtrics.com/" />

      <LogoCard title="Quantico AI" href="https://quantico.ai" />

      <LogoCard title="QuickMetrix" href="http://www.quickmetrix.com/" />

      <LogoCard title="Radarr Technologies" href="http://www.radarr.com/?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Relo Metrics" href="https://relometrics.com/?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="samdesk" href="https://www.samdesk.io/" />

      <LogoCard title="Sensika Technologies Ltd." href="https://sensika.com/" />

      <LogoCard title="Shareablee" href="http://www.shareablee.com/?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Shuttlerock Japan" href="https://www.shuttlerock.co.jp/" />

      <LogoCard title="Sift AI" href="https://www.getsift.ai/" />

      <LogoCard title="Signal" href="https://www.getsignal.info/" />

      <LogoCard title="Signify Group Limited" href="https://www.signify.ai/" />

      <LogoCard title="Simplify360" href="http://simplify360.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Smart Share Inc." href="https://www.smartshare.jp/" />

      <LogoCard title="Socialdatabase" href="https://www.socialdatabase.com/" />

      <LogoCard title="SocialDog" href="https://social-dog.net/" />

      <LogoCard title="SocialHub" href="https://socialhub.io/" />

      <LogoCard title="Socialie by PhotoShelter" href="https://go.photoshelter.com/socialie/social-content-distribution/" />

      <LogoCard title="SocialBee" href="https://socialbee.com/" />

      <LogoCard title="SocialPilot" href="https://www.socialpilot.co/?utm_source=twitter_data_website&utm_medium=twitter%20enterprise%20customer%20" />

      <LogoCard title="Social Market Analytics" href="https://www.socialmarketanalytics.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Sparta" href="https://dtecbw.de/sparta" />

      <LogoCard title="Sprinklr" href="https://partners.x.com/en/partners/sprinklr" />

      <LogoCard title="Sprout Social" href="https://partners.x.com/en/partners/sprout-social" />

      <LogoCard title="Starcount" href="https://www.starcount.com/" />

      <LogoCard title="StatSocial" href="https://www.statsocial.com" />

      <LogoCard title="Stilingue" href="https://stilingue.com.br/?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Synthesio" href="https://www.synthesio.com/?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Talkwalker" href="http://www.talkwalker.com?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Telmar Helixa" href="https://www.helixa.ai/" />

      <LogoCard title="Teneo Holdings" href="https://www.teneo.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="The Saudi Center for Opinion Polling (SCOP)" href="http://www.scop.sa" />

      <LogoCard title="True Anthem" href="https://www.trueanthem.com/" />

      <LogoCard title="Turkcell Global Bilgi" href="https://developer.x.comwww.global-bilgi.com.tr.html" />

      <LogoCard title="Unique Vision Company, Japan" href="https://www.uniquevision.co.jp/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="User Local, Inc." href="https://www.userlocal.jp/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Verint" href="https://www.verint.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Visibrain" href="https://www.visibrain.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="v-tracker" href="https://www.vtracker.com.br" />

      <LogoCard title="WaveMetrix" href="https://www.wavemetrix.com/?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />

      <LogoCard title="Zendesk" href="https://www.zendesk.com/" />

      <LogoCard title="ZeroFOX" href="https://zerofox.com?utm_source=data_website&utm_medium=twitter%20enterprise%20customer%20directory" />

      <LogoCard title="Zoomph" href="https://zoomph.com" />

      <LogoCard title="Zoho" href="http://www.zoho.com?utm_source=twitter_data_website&utm_medium=enterprise%20customer%20directory" />
    </CardGroup>
  </Tab>
</Tabs>


# X Official Partner
Source: https://docs.x.com/enterprise/partner-directory

Directory of X Official Partners offering tools and services built on the X API, including analytics, content moderation, ad management, and more.

## Build your business with X Official Partners

###### Tap into the public conversation on X and turn insights into action with solutions from our partners.

<br />

<div>
  <Button href="https://partners.x.com/en/find-a-partner">
    Find a partner
  </Button>

  <Button href="https://partners.x.com/en/about-the-program">
    Learn more
  </Button>
</div>

## Work with a trusted X Official Partner to expand what's possible for your business

Our partners are vetted for excellence and can provide technology to help you:

* Understand consumer trends and preferences 
* Collect and analyze product and service feedback 
* Engage with customers and resolve issues 
* Be alerted to breaking news and events 
* Create, publish, and analyze content across social channels 
* And more!

## Discover the right Official Partner for your business

<br />

<Banner title="Official Partners represent excellence, value, and trust" description="Each Official Partner has been selected for the program after an extensive evaluation. Our partners are continuously reviewed by X, as this invitation-only program holds its members to the highest performance standards, in order to deliver great experiences for brands." />

### Official Partners represent excellence, value, and trust

Each Official Partner has been selected for the program after an extensive evaluation. Our partners are continuously reviewed by X, as this invitation-only program holds its members to the highest performance standards, in order to deliver great experiences for brands.

<Button href="https://partners.x.com/en/about-the-program">
  Learn about the program
</Button>

## See our partners' impressive work

<CardGroup>
  <StoryCard title="NASA uses X audience insights to take fans to new frontiers" href="https://partners.x.com/en/partner-resources/nasa-uses-twitter-audience-insights-to-take-fans-to-new-frontier" />

  <StoryCard title="The beauty in X" href="https://partners.x.com/en/partner-resources/the-beauty-in-twitter" />

  <StoryCard title="Analyze #ExtremeWeather conversation on X" href="https://developer.x.com/en/use-cases/build-for-good/extreme-weather" />
</CardGroup>


# Ads API Access Form
Source: https://docs.x.com/forms/ads-api-access

Request access to the X Ads API by submitting your details, including intended use case and app information, for review and approval.

<Form />


# Application for Trial Enterprise Access
Source: https://docs.x.com/forms/application-trial

Apply for trial access to the X Enterprise API. Submit company information, intended use cases, and contact details to request an evaluation environment.

<Form />


# Billing support form
Source: https://docs.x.com/forms/billing-support

Contact X API billing support for help with invoices, payment methods, subscription changes, refunds, plan upgrades, and account-related billing issues.

Get billing support for Self-serve and Enterprise API subscriptions.

<Form />


# Enterprise Access Form
Source: https://docs.x.com/forms/enterprise-api-interest

Request access to the X Enterprise API by submitting company details, intended use case, expected data volume, and contact information for review.

<Form />


# Government End User Request Form
Source: https://docs.x.com/forms/government-end-user-request

Government and public sector form to request X API access, providing agency details, intended use case, and compliance information for review.

<Form />


# Survey: Product Tracks & Commercial Use
Source: https://docs.x.com/forms/survey

Share feedback about your X API product track, commercial use case, integration plans, and developer experience to help guide future platform changes.

<Form />


# Initial use case application for new X API customers
Source: https://docs.x.com/forms/use-case/initial

Initial application form for prospective customers to request access to X API enterprise products by describing the intended use case and integration plan.

<Form />


# Use case modification request for X API customers
Source: https://docs.x.com/forms/use-case/modification

Form for existing X API enterprise customers to request modifications to a previously approved use case, including changes to data products or workflows.

<Form />


# Public sector use case request for X API customers
Source: https://docs.x.com/forms/use-case/public-sector

Form for existing public-sector X API customers, including government agencies, to submit a request related to a contracted enterprise data use case.

<Form />


# Upgrade your enterprise account and add data products
Source: https://docs.x.com/forms/use-case/upgrade

Form for existing X API enterprise customers to upgrade their account and add new data products such as Search, Filtered Stream, or Account Activity.

<Form />


# OAuth API reference index
Source: https://docs.x.com/fundamentals/authentication/api-reference

Reference index of X authentication endpoints across OAuth 1.0a and OAuth 2.0, including request tokens, authorize, access tokens, and token revocation.

### OAuth 1.0a

|                                                                                                                                                           |                                                                                                                  |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
| **Purpose**                                                                                                                                               | Method                                                                                                           |
| Step 1 of the 3-legged OAuth flow and Sign in with X  <br />Allows a Consumer application to obtain an OAuth Request Token to request user authorization. | [POST oauth/request\_token](/resources/fundamentals/authentication/api-reference#post-oauth-request-token)       |
| Step 2 of the 3-legged OAuth flow and Sign in with X  <br />Allows a Consumer application to use an OAuth Request Token to request user authorization.    | [GET oauth/authenticate](/resources/fundamentals/authentication/api-reference#get-oauth-authenticate)            |
| Step 2 of the 3-legged OAuth flow and Sign in with X  <br />Allows a Consumer application to use an OAuth Request Token to request user authorization.    | [GET oauth/authorize](/resources/fundamentals/authentication/api-reference#get-oauth-authorize)                  |
| Step 3 of the 3-legged OAuth flow and Sign in with X  <br />Allows a Consumer application to exchange the OAuth Request Token for an OAuth Access Token.  | [POST oauth/access\_token](/resources/fundamentals/authentication/api-reference#post-oauth-access-token)         |
| Allows a registered application to revoke an issued OAuth Access Token.                                                                                   | [POST oauth/invalidate\_token](/resources/fundamentals/authentication/api-reference#post-oauth-invalidate-token) |

### OAuth 2.0 Bearer Token

|                                                                                                                                                        |                                                                                                                    |
| :----------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| **Purpose**                                                                                                                                            | Method                                                                                                             |
| Allows a registered App to generate an OAuth 2 app-only Bearer Token, which can be used to make API requests on an App's behalf, without user context. | [POST oauth2/token](/resources/fundamentals/authentication/api-reference#post-oauth2-token)                        |
| Allows a registered App to revoke an issued OAuth 2 app-only Bearer Token.                                                                             | [POST oauth2/invalidate\_token](/resources/fundamentals/authentication/api-reference#post-oauth2-invalidate-token) |

### POST oauth/request\_token

Allows a Consumer application to obtain an OAuth Request Token to request user authorization. This method fulfills [Section 6.1](https://oauth.net/core/1.0/#auth_step1) of the [OAuth 1.0 authentication flow](http://oauth.net/core/1.0/#anchor9).

**We require you use HTTPS for all OAuth authorization steps.**

**Usage Note:** Only ASCII values are accepted for the `oauth_nonce`

**Resource URL[](#resource-url "Permalink to this headline")**

`https://api.x.com/oauth/request_token`

**Resource Information[](#resource-information "Permalink to this headline")**

|                          |      |
| :----------------------- | :--- |
| Response formats         | JSON |
| Requires authentication? | No   |
| Rate limited?            | Yes  |

**Parameters[](#parameters "Permalink to this headline")**

| Name                  | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Example                                                          |
| :-------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| oauth\_callback       | required | For OAuth 1.0a compliance this parameter is **required** . The value you specify here will be used as the URL a user is redirected to should they approve your application's access to their account. Set this to `oob` for out-of-band pin mode. This is also how you specify custom callbacks for use in desktop/mobile applications. Always send an `oauth_callback` on this step, regardless of a pre-registered callback.<br /><br />We require that any callback URL used with this endpoint will have to be configured within the App’s settings on developer.x.com\* | `http://themattharris.local/auth.php` `twitterclient://callback` |
| x\_auth\_access\_type | optional | Overrides the access level an application requests to a users account. Supported values are `read` or `write` . This parameter is intended to allow a developer to register a read/write application but also request read only access when appropriate.                                                                                                                                                                                                                                                                                                                     |                                                                  |

Learn more about how to approve your callback URLs on [this page](/resources/fundamentals/developer-apps#callback-urls).

**Please note** - You can view and edit your existing [X apps](/resources/fundamentals/developer-apps) via the [X app dashboard](https://developer.x.com/en/apps) if you are logged into your X account on developer.x.com.

**Example request[](#example-request "Permalink to this headline")**

Request URL: `POST https://api.x.com/oauth/request_token`

Request POST Body: *N/A*

Authorization Header: `OAuth oauth_nonce="K7ny27JTpKVsTgdyLdDfmQQWVLERj2zAK5BslRsqyw", oauth_callback="http%3A%2F%2Fmyapp.com%3A3005%2Ftwitter%2Fprocess_callback", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1300228849", oauth_consumer_key="OqEqJeafRSF11jBMStrZz", oauth_signature="Pc%2BMLdv028fxCErFyi8KXFM%2BddU%3D", oauth_version="1.0"`

Response: `oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik&oauth_token_secret=Kd75W4OQfb2oJTV0vzGzeXftVAwgMnEK9MumzYcM&oauth_callback_confirmed=true`

### GET oauth/authorize

Allows a Consumer application to use an OAuth Request Token to request user authorization. This method fulfills [Section 6.2](http://oauth.net/core/1.0/#auth_step2) of the [OAuth 1.0 authentication flow](http://oauth.net/core/1.0/#anchor9). Desktop applications must use this method (and cannot use [GET oauth / authenticate](/resources/fundamentals/authentication/api-reference#get-oauth-authenticate)).

**Usage Note:** An `oauth_callback` is never sent to this method, provide it to [POST oauth / request\_token](/resources/fundamentals/authentication/api-reference#post-oauth-request-token) instead.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://api.x.com/oauth/authorize`

**Resource Information[](#resource-information "Permalink to this headline")**

|                          |      |
| :----------------------- | :--- |
| Response formats         | JSON |
| Requires authentication? | Yes  |
| Rate limited?            | Yes  |

**Parameters[](#parameters "Permalink to this headline")**

|              |          |                                                                                               |               |         |
| :----------- | :------- | :-------------------------------------------------------------------------------------------- | :------------ | :------ |
| Name         | Required | Description                                                                                   | Default Value | Example |
| force\_login | optional | Forces the user to enter their credentials to ensure the correct users account is authorized. |               |         |
| screen\_name | optional | Prefills the username input box of the OAuth login screen with the given value.               |               |         |

**Example request[](#example-request "Permalink to this headline")**

Send the user to the `oauth/authorize` step in a web browser, including an oauth\_token parameter:
`https://api.x.com/oauth/authorize?oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik`

### GET oauth/authenticate

Allows a Consumer application to use an OAuth `request_token` to request user authorization.

This method is a replacement of [Section 6.2](http://oauth.net/core/1.0/#auth_step2) of the [OAuth 1.0 authentication flow](http://oauth.net/core/1.0/#anchor9) for applications using the callback authentication flow. The method will use the currently logged in user as the account for access authorization unless the `force_login` parameter is set to `true`.

This method differs from [GET oauth / authorize](/resources/fundamentals/authentication/api-reference#get-oauth-authorize) in that if the user has already granted the application permission, the redirect will occur without the user having to re-approve the application. To realize this behavior, you must enable the *Use Sign in with X* setting on your [application record](https://developer.x.com/apps).

**Resource URL[](#resource-url "Permalink to this headline")**

`https://api.x.com/oauth/authenticate`

**Resource Information[](#resource-information "Permalink to this headline")**

|                          |      |
| :----------------------- | :--- |
| Response formats         | JSON |
| Requires authentication? | Yes  |
| Rate limited?            | Yes  |

**Parameters[](#parameters "Permalink to this headline")**

|              |          |                                                                                               |               |         |
| :----------- | :------- | :-------------------------------------------------------------------------------------------- | :------------ | :------ |
| Name         | Required | Description                                                                                   | Default Value | Example |
| force\_login | optional | Forces the user to enter their credentials to ensure the correct users account is authorized. |               | *true*  |
| screen\_name | optional | Prefills the username input box of the OAuth login screen with the given value.               |               |         |

**Example request[](#example-request "Permalink to this headline")**

Send the user to the `oauth/authenticate` step in a web browser, including an oauth\_token parameter:
`https://api.x.com/oauth/authenticate?oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik`

### POST oauth/access\_token

Allows a Consumer application to exchange the OAuth Request Token for an OAuth Access Token. This method fulfills [Section 6.3](http://oauth.net/core/1.0/#auth_step3) of the [OAuth 1.0 authentication flow](http://oauth.net/core/1.0/#anchor9).

**Resource URL[](#resource-url "Permalink to this headline")**

`https://api.x.com/oauth/access_token`

**Resource Information[](#resource-information "Permalink to this headline")**

|                          |      |
| :----------------------- | :--- |
| Response formats         | JSON |
| Requires authentication? | Yes  |
| Rate limited?            | Yes  |

**Parameters[](#parameters "Permalink to this headline")**

|                 |          |                                                                                                                                                                                                                                                                                                                                                                          |               |         |
| :-------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ | :------ |
| Name            | Required | Description                                                                                                                                                                                                                                                                                                                                                              | Default Value | Example |
| oauth\_token    | required | The oauth\_token here must be the same as the oauth\_token returned in the request\_token step.                                                                                                                                                                                                                                                                          |               |         |
| oauth\_verifier | required | If using the OAuth web-flow, set this parameter to the value of the *oauth\_verifier* returned in the callback URL. If you are using out-of-band OAuth, set this value to the pin-code. For OAuth 1.0a compliance this parameter is **required**. OAuth 1.0a is strictly enforced and applications not using the *oauth\_verifier* will fail to complete the OAuth flow. |               |         |

**Example request[](#example-request "Permalink to this headline")**

`POST https://api.x.com/oauth/access_token?oauth_token=qLBVyoAAAAAAx72QAAATZxQWU6P&oauth_verifier=ghLM8lYmAxDbaqL912RZSRjCCEXKDIzx`

From PIN-based `POST https://api.x.com/oauth/access_token?oauth_token=9Npq8AAAAAAAx72QBRABZ4DAfY9&oauth_verifier=4868795`

**Example response[](#example-response "Permalink to this headline")**

`oauth_token=6253282-eWudHldSbIaelX7swmsiHImEL4KinwaGloHANdrY&oauth_token_secret=2EEfA6BG5ly3sR3XjE0IBSnlQu4ZrUzPiYTmrkVU&user_id=6253282&screen_name=xapi`

### POST oauth/invalidate\_token

Allows a registered application to revoke an issued OAuth access\_token by presenting its client credentials. Once an access\_token has been invalidated, new creation attempts will yield a different Access Token and usage of the invalidated token will no longer be allowed.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://api.x.com/1.1/oauth/invalidate_token`

**Resource Information[](#resource-information "Permalink to this headline")**

|                          |                                                                             |
| :----------------------- | :-------------------------------------------------------------------------- |
| Response formats         | JSON                                                                        |
| Requires authentication? | Yes - User context with the access tokens that you would like to invalidate |
| Rate limited?            | Yes                                                                         |

**Example request[](#example-request "Permalink to this headline")**

```bash theme={null}
        curl --request POST
          --url 'https://api.x.com/1.1/oauth/invalidate_token.json'
          --header 'authorization: OAuth oauth_consumer_key="CLIENT_KEY",
         oauth_nonce="AUTO_GENERATED_NONCE", oauth_signature="AUTO_GENERATED_SIGNATURE",
         oauth_signature_method="HMAC-SHA1", oauth_timestamp="AUTO_GENERATED_TIMESTAMP",
         oauth_token="ACCESS_TOKEN", oauth_version="1.0"'
```

**Example response[](#example-response "Permalink to this headline")**

```bash theme={null}
        HTTP/1.1 200 OK
        Content-Type: application/json; charset=utf-8
        Content-Length: 127
        ...

        {"access_token":"ACCESS_TOKEN"}
```

**Example error response after token has been invalidated[](#example-error-response-after-token-has-been-invalidated "Permalink to this headline")**

```bash theme={null}
        HTTP/1.1 401 Authorization Required
        ...

        {"errors": [{
          "code": 89,
          "message": "Invalid or expired token."}
        ]}
```

### POST oauth2/token

Allows a registered application to obtain an OAuth 2 Bearer Token, which can be used to make API requests on an application's own behalf, without a user context. This is called [Application-only authentication](/resources/fundamentals/authentication/oauth-2-0/application-only).

A Bearer Token may be invalidated using oauth2/invalidate\_token. Once a Bearer Token has been invalidated, new creation attempts will yield a different Bearer Token and usage of the previous token will no longer be allowed.

Only one bearer token may exist outstanding for an application, and repeated requests to this method will yield the same already-existent token until it has been invalidated.

Successful responses include a JSON-structure describing the awarded Bearer Token.

Tokens received by this method should be cached. If attempted too frequently, requests will be rejected with an HTTP 403 with code 99.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://api.x.com/oauth2/token`

**Resource Information[](#resource-information "Permalink to this headline")**

|                          |                                                                                         |
| :----------------------- | :-------------------------------------------------------------------------------------- |
| Response formats         | JSON                                                                                    |
| Requires authentication? | Yes - Basic auth with your API key as your username and API key secret as your password |
| Rate limited?            | Yes                                                                                     |

**Parameters[](#parameters "Permalink to this headline")**

|             |          |                                                                                                                                                                                                                                                     |               |                       |
| :---------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ | :-------------------- |
| Name        | Required | Description                                                                                                                                                                                                                                         | Default Value | Example               |
| grant\_type | required | Specifies the type of grant being requested by the application. At this time, only *client\_credentials* is allowed. See [Application-Only Authentication](/resources/fundamentals/authentication/oauth-2-0/application-only) for more information. |               | *client\_credentials* |

**Example request[](#example-request "Permalink to this headline")**

```bash theme={null}
    POST /oauth2/token HTTP/1.1
    Host: api.x.com
    User-Agent: My X App v1.0.23
    Authorization: Basic eHZ6MWV2R ... o4OERSZHlPZw==
    Content-Type: application/x-www-form-urlencoded;charset=UTF-8
    Content-Length: 29
    Accept-Encoding: gzip

    grant_type=client_credentials
```

**Example response:**

```bash theme={null}
    HTTP/1.1 200 OK
    Status: 200 OK
    Content-Type: application/json; charset=utf-8
    ...
    Content-Encoding: gzip
    Content-Length: 140

    {"token_type":"bearer","access_token":"AAAA%2FAAA%3DAAAAAAAA"}
```

### POST oauth2/invalidate\_token

Allows a registered application to revoke an issued oAuth 2.0 Bearer Token by presenting its client credentials. Once a Bearer Token has been invalidated, new creation attempts will yield a different Bearer Token and usage of the invalidated token will no longer be allowed.

Successful responses include a JSON-structure describing the revoked Bearer Token.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://api.x.com/oauth2/invalidate_token`

**Resource Information[](#resource-information "Permalink to this headline")**

|                          |                                                                                                                                                                               |
| :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Response formats         | JSON                                                                                                                                                                          |
| Requires authentication? | Yes - [oAuth 1.0a](/resources/fundamentals/authentication/oauth-1-0a) with the application's consumer API keys and the application owner's access token & access token secret |
| Rate limited?            | Yes                                                                                                                                                                           |

**Parameters[](#parameters "Permalink to this headline")**

| Name          | Required | Description                                                     |
| :------------ | :------- | :-------------------------------------------------------------- |
| access\_token | required | The value of the bearer token that you would like to invalidate |

**Example request[](#example-request "Permalink to this headline")**

```bash theme={null}
        curl --request POST
          --url 'https://api.x.com/oauth2/invalidate_token?access_token=AAAA%2FAAA%3DAAAAAAAA'
          --header 'authorization: OAuth oauth_consumer_key="CLIENT_KEY",
         oauth_nonce="AUTO_GENERATED_NONCE", oauth_signature="AUTO_GENERATED_SIGNATURE",
         oauth_signature_method="HMAC-SHA1", oauth_timestamp="AUTO_GENERATED_TIMESTAMP",
         oauth_token="ACCESS_TOKEN", oauth_version="1.0"'
```

**Example response[](#example-response "Permalink to this headline")**

```
         Status: 200 OK
         Content-Type: application/json; charset=utf-8
         Content-Length: 135
         ...
       {
        "access_token": "AAAA%2FAAA%3DAAAAAAAA"
        }
```


# Basic authentication
Source: https://docs.x.com/fundamentals/authentication/basic-auth

Use HTTP Basic authentication to access X enterprise APIs like PowerTrack, Decahose, and Search by sending your email and password over HTTPS.

## Basic authentication

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 must pass a valid email address and password combination as an authorization header for each request. The email and password combination are the same ones that you will use to access the [enterprise API console](https://console.gnip.com/), and can be edited from within this console. 

When building a request using Basic Authentication, make sure you add the Authentication: Basic HTTP header with encoded credentials over HTTPS.

In the following cURL request example, you would replace `<email_address>` and `<password>` with your credentials before sending the request:

```bash theme={null}
curl -v --compressed -u<email_address>:<password>
    "https://gnip-api.x.com/search/30day/accounts/<account-name>/prod/counts.json?query=from%3Axdevelopers"
```

**APIs that require basic authentication:**

* [PowerTrack API](/x-api/enterprise-gnip-2.0/powertrack-api) enterprise
* [Decahose stream API](http://localhost:3000/x-api/enterprise-gnip-2.0/fundamentals/decahose-api) enterprise
* [30-Day Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api) enterprise
* [Full-Archive Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api) enterprise
* [Usage API](/x-api/enterprise-gnip-2.0/fundamentals/usage) enterprise


# OAuth FAQ
Source: https://docs.x.com/fundamentals/authentication/faq

Answers to common questions about OAuth 1.0a, OAuth 2.0, access tokens, scopes, and authentication errors when working with the X API.

## General

<AccordionGroup>
  <Accordion title="What is OAuth?">
    OAuth is an authentication protocol that allows users to approve an application to act on their behalf without sharing their password. More information can be found at [oauth.net](http://oauth.net/).
  </Accordion>

  <Accordion title="How do I generate access tokens?">
    You must have a [X app](/resources/fundamentals/developer-apps) to generate access tokens. Learn more about access tokens [here](/resources/fundamentals/authentication#oauth-1-0a-2). 
  </Accordion>

  <Accordion title="How do I create a X app?">
    You must have a [developer account](/resources/fundamentals/developer-portal) to create a [X app](/resources/fundamentals/developer-apps). You can sign up for one [here](https://developer.x.com/en/portal/petition/essential/basic-info).
  </Accordion>

  <Accordion title="If I already have a X app, how do I view and edit that app?">
    You can view and edit your app from the [X app dashboard](https://developer.x.com/content/developer-twitter/en/apps) if you are logged into your X account on developer.x.com.
  </Accordion>
</AccordionGroup>

## Technical

<AccordionGroup>
  <Accordion title="How long does an access token last?">
    Access tokens are not explicitly expired. An access token will be invalidated if a user explicitly revokes an application in their X account settings, or if X suspends an application. If an application is suspended, there will be a note in the [X app](/resources/fundamentals/developer-apps) dashboard stating that it has been suspended.
  </Accordion>

  <Accordion title="What if an access token becomes invalid?">
    Assume a user’s access token *may* become invalid at any time. If this happens, prompt the user to re-authorize the application. Ensuring that this situation is handled gracefully is important for a good user experience.
  </Accordion>

  <Accordion title="The application registration page asks about read/write access. What constitutes a write?">
    Many users trust an application to read their information, but not necessarily change their user profile information or post new statuses. Updating information via the X API - be it name, location or adding a new status - requires an HTTP POST. Any API method that requires an HTTP POST is considered a write method and requires read & write access.
  </Accordion>
</AccordionGroup>


# Best practices
Source: https://docs.x.com/fundamentals/authentication/guides/authentication-best-practices

Your API keys and tokens should be guarded very carefully. These credentials are directly tied to your developer App and those X account that have authorized.

Your API keys and tokens should be guarded very carefully. 

These credentials are directly tied to your [developer App](/resources/fundamentals/developer-apps) and those X account that have authorized you to make requests on behalf of them. If your keys are compromised, bad actors could use them to make requests to the X endpoints on behalf of your developer App or its authorized users, which could mean their requests might cause you to hit unexpected rate limits, use up your paid access allotment, or even cause your developer App to be suspended.

The following sections include best practices that should be considered when managing your API keys and tokens.

## Regenerate API keys and tokens

In the event that you believe that your API keys has been exposed, you should regenerate your API keys by following these steps:

1. Navigate to the [Developer Console's "Apps" page](https://developer.x.com/en/portal/projects-and-apps.html).
2. Click on the "Keys and tokens" icon (🗝 ) next to the relevant App.
3. Click on the "Regenerate" button next to the set of keys and tokens that you would like to regenerate. 

If you would prefer to regenerate your Access Tokens or Bearer Tokens programmatically, you can do so using our authentication endpoints.

* If you would like to regenerate your Access Tokens, you must invalidate your tokens using the [POST oauth/invalidate\_token](/resources/fundamentals/authentication/api-reference#post-oauth2-invalidate-token) endpoint, then regenerate your tokens using the [3-legged OAuth flow](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens).
* If you would like to regenerate your Bearer Token, you must invalidate your token using the [POST oauth2/invalidate\_token](/resources/fundamentals/authentication/api-reference#post-oauth2-invalidate-token) endpoint, then regenerate your token using the [POST oauth2/token](/resources/fundamentals/authentication/api-reference#post-oauth2-token) endpoint.

## Having a central file for your secrets

Having a file such as .ENV file or any other sort of .yaml file to contain your secrets is an option that could be helpful but be sure to have a strong .gitignore file that can prevent you from accidentally committing these to a git repository. 

## Environment variables

Writing code that utilizes environment variables might be helpful. 

An example of this is as follows written in Python:

```python theme={null}
import os

consumer_key = os.environ.get("CONSUMER_KEY")

consumer_secret = os.environ.get("CONSUMER_SECRET")
```

Inside of your terminal you would want to write something like this:

```bash theme={null}
export CONSUMER_KEY='xxxxxxxxxxxxxxxxxxx'
export CONSUMER_SECRET='xxxxxxxxxxxxxxxxxxxxxxx'
```

## Source code and version control

The most common security mistakes made by developers are having API keys and tokens committed to source code in accessible version control systems like GitHub and BitBucket. Many of these code repositories are publicly accessible. This mistake is made so often in public code repositories that there are lucrative bots that scrape for API keys.

* Use server environment variables. By storing API keys in environment variables, you keep them out of your code and version control. This also allows you to use different keys for different environments easily.
* Use a configuration file excluded from source control. Add the filename to your [.gitignore](https://git-scm.com/docs/gitignore) file to exclude the file from being tracked by version control.
* If you remove the API keys from your code after you have used version control, the API keys are likely still accessible by accessing previous versions of your codebase. Regenerate your API keys, as described in the next section.

## Databases

If you need to store your access tokens in a database, please keep the following in mind:

* Restrict access to the database in a way such that the access tokens are only readable by the owner of the token.
* Restrict edit/write privileges to the database table for access tokens - this should be automated with the key management system.
* Encrypt access tokens before storing in any data stores.

## Password management tools

Password management tools such as 1password or Last Pass can be helpful in keeping your keys and tokens in a secure place. You might want to avoid sharing these inside of a shared team password management tool.

## Web storage & cookies

There are two types of web storage: LocalStorage and SessionStorage. These were created as improvements to using Cookies since the storage capacity for web storage is much higher than Cookie storage. However, there are different pros and cons to each of these storage options.
 

**Web Storage: LocalStorage**

Anything stored in local web storage is persistent. This means that the data will persist until the data is explicitly deleted. Depending on the needs of your project, you might view this as a positive. However, you should be mindful of using LocalStorage, since any changes/additions to data will be available on all future visits to the webpage in question. We would not usually recommend using LocalStorage, although there may be a few exceptions to this. If you decide to use LocalStorage, it is good to know that it supports the same-origin policy, so all data stored here will only be available via the same origin. An added performance perk of using LocalStorage would be a resulting decrease in client-server traffic since the data does not have to be sent back to the server for every HTTP request.
 

**Web Storage: SessionStorage**

SessionStorage is similar to LocalStorage, but the key difference is that SessionStorage is not persistent. Once the window (or tab, depending on which browser you are using) that was used to write to SessionStorage is closed, the data will be lost. This is useful in restricting read access to your token within a user session. Using SessionStorage is normally more preferable than LocalStorage when thinking in terms of security. Like LocalStorage, the perks of same-origin policy support and decreased client-server traffic apply to SessionStorage as well.
 

**Cookies**

Cookies are the more traditional way to store session data. You can set an expiration time for each cookie, which would allow for ease of revocability and restriction of access. However, the client-server traffic would definitely increase when using cookies, since the data is being sent back to the server for every HTTP request. If you decide to use cookies, you need to protect against session hijacking. By default, cookies are sent in plaintext over HTTP, which makes their contents vulnerable to packet sniffing and/or man-in-the-middle attacks where attackers may modify your traffic. You should always enforce HTTPS to protect your data in transit. This will provide confidentiality, integrity (of the data), and authentication. However, if your web application or site is available both through HTTP and HTTPS, you will also want to use the 'Secure' flag on the cookie. This will prevent attackers from being able to send links to the HTTP version of your site to a user and listening in on the resulting HTTP request generated.

Another secondary defense against session hijacking when using cookies would be to validate the user's identity again before any high-impact actions are carried out. One other flag to consider for improving the security of your cookies would be the 'HttpOnly' flag. This flag tells the browser that the cookie in question shall only be accessible from the server specified. Any attempts made by client-side scripts would be forbidden by this flag, therefore helping to protect against most cross-site scripting (XSS) attacks.


# Log in with X
Source: https://docs.x.com/fundamentals/authentication/guides/log-in-with-x

Implement Sign in with X on websites and mobile apps using the OAuth 1.0a request token flow to authenticate users and obtain access tokens.

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 registered user account in as little as one click. This works on websites, iOS, mobile, and desktop applications.

## Features

* Ease of use - A new visitor to your site only has to click two buttons in order to log in for the first time.
* X integration - The Log in with X flow can grant authorization to use X APIs on your users' behalf.
* OAuth based - A wealth of client libraries and example code are compatible with the Log in with X API.

## Available for

* Browsers - If your users can access a browser, you can integrate with Log in with X. Learn about the browser sign in flow.
* Mobile devices - Any web-connected mobile device can take advantage of Log in with X. Learn about the mobile sign in flow.

## Implementing Log in with X

The browser and mobile web implementations of Log in with X are based on OAuth. This page demonstrates the requests needed to obtain an access token for the sign in flow.

To use the “Log in with X" flow, please go to your [X app settings](/resources/fundamentals/developer-apps) and ensure that the *"Allow this app to be used to Sign in with X?*” option is enabled.

This page assumes that the reader knows how to sign requests using the OAuth 1.0a protocol. If you want to know how to sign a request, read the [Authorizing a request](/resources/fundamentals/authentication/oauth-1-0a/authorizing-a-request) page.

If you want to check the signing of the requests on this page, the consumer secret used is: L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg. This value is for test purposes and will not work for real requests.

The three steps for implementing Log in with X through obtaining a request token, redirecting a user, and converting a request token into an access token are listed below.

<Tabs>
  <Tab title="Step 1">
    ### Step 1: Obtaining a request token

    To start a sign-in flow, your [X app](/resources/fundamentals/developer-apps) must obtain a request token by sending a signed message to [POST oauth/request\_token](/resources/fundamentals/authentication/api-reference#post-oauth-request-token). The only unique parameter in this request is oauth\_callback, which must be a URL-encoded version of the URL you wish your user to be redirected to when they complete step 2. The remaining parameters are added by the OAuth signing process.

    <Note>
      **Note:** Any [callback URL](/resources/fundamentals/developer-apps#callback-urls) that you use with the [POST oauth/request\_token](/resources/fundamentals/authentication/api-reference#post-oauth-request-token) endpoint will have to be registered within the [X app settings](/resources/fundamentals/developer-apps) in the [Developer Console](/resources/fundamentals/developer-portal).
    </Note>

    <Frame>
      <img alt="" />
    </Frame>

    **Example request (Authorization header has been wrapped):**

    ```
    POST /oauth/request_token HTTP/1.1
    User-Agent: themattharris' HTTP Client
    Host: api.x.com
    Accept: */*
    Authorization:
            OAuth oauth_callback="http%3A%2F%2Flocalhost%2Fsign-in-with-twitter%2F",
                  oauth_consumer_key="cChZNFj6T5R0TigYB9yd1w",
                  oauth_nonce="ea9ec8429b68d6b77cd5600adbbb0456",
                  oauth_signature="F1Li3tvehgcraF8DMJ7OyxO4w9Y%3D",
                  oauth_signature_method="HMAC-SHA1",
                  oauth_timestamp="1318467427",
                  oauth_version="1.0"
    ```

    Your app should examine the HTTP status of the response. Any value other than 200 indicates a failure. The body of the response will contain the oauth\_token, oauth\_token\_secret, and oauth\_callback\_confirmed parameters. Your app should verify that oauth\_callback\_confirmed is true and store the other two values for the next steps.

    **Example response (response body has been wrapped):**

    ```
    HTTP/1.1 200 OK
    Date: Thu, 13 Oct 2011 00:57:06 GMT
    Status: 200 OK
    Content-Type: text/html; charset=utf-8
    Content-Length: 146
    Pragma: no-cache
    Expires: Tue, 31 Mar 1981 05:00:00 GMT
    Cache-Control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0
    Vary: Accept-Encoding
    Server: tfe

    oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0&
    oauth_token_secret=veNRnAWe6inFuo8o2u8SLLZLjolYDmDP7SzL0YfYI&
    oauth_callback_confirmed=true

    ```
  </Tab>

  <Tab title="Step 2">
    ### Step 2: Redirecting the user

    The next step is to direct the user to X so that they may complete the appropriate flow, as described in Browser sign-in flow below. Direct the user to [GET oauth/authenticate](/resources/fundamentals/authentication/api-reference#get-oauth-authenticate), and the request token obtained in step 1 should be passed as the oauth\_token parameter.

    The most seamless way for a website to implement this would be to issue an HTTP 302 redirect as the response to the original “sign in” request. Mobile and desktop apps should open a new browser window or direct to the URL via an embedded web view.

    **Example URL to redirect to:**

    [https://api.x.com/oauth/authenticate?oauth\_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0](https://api.x.com/oauth/authenticate?oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0)

    The sign in endpoint will behave in one of three ways depending on the user’s status:

    1. **Signed in and approved**: If the user is signed in on x.com and has already approved the calling application, they will be immediately authenticated and returned to the callback URL with a valid OAuth request token. The redirect to x.com is not obvious to the user.
    2. **Signed in but not approved**: If the user is signed in to x.com but has not approved the calling application, a request to share access with the calling application will be shown. After accepting the authorization request, the user will be redirected to the callback URL with a valid OAuth request token.
    3. **Not signed in**: If the user is not signed in on x.com, they will be prompted to enter their credentials and grant access for the application to access their information on the same screen. Once signed in, the user will be returned to the callback URL with a valid OAuth request token.

    Upon a successful authentication, your callback\_url would receive a request containing the oauth\_token and oauth\_verifier parameters. Your application should verify that the token matches the request token received in step 1.

    **Request from client’s redirect (querystring parameters wrapped):**

    ```
    GET /sign-in-with-twitter/?
            oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0&
            oauth_verifier=uw7NjWHT6OJ1MpJOXsHfNxoAhPKpgI8BlYDhxEjIBY HTTP/1.1
    Host: localhost
    User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.5 (KHTML, like Gecko) Chrome/16.0.891.1 Safari/535.5
    Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
    Referer: http://localhost/sign-in-with-twitter/
    Accept-Encoding: gzip,deflate,sdch
    Accept-Language: en-US,en;q=0.8
    Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3
    ```
  </Tab>

  <Tab title="Step 3">
    ### Step 3: Converting the request token to an access token

    To render the request token into a usable access token, your application must make a request to the [POST oauth/access\_token](/resources/fundamentals/authentication/api-reference#post-oauth-access-token) endpoint, containing the oauth\_verifier value obtained in step 2. The request token is also passed in the oauth\_token portion of the header, but this will have been added by the signing process.

    **Example request (Authorization header wrapped):**

    ```
    POST /oauth/access_token HTTP/1.1
    User-Agent: themattharris' HTTP Client
    Host: api.x.com
    Accept: */*
    Authorization: OAuth oauth_consumer_key="cChZNFj6T5R0TigYB9yd1w",
                          oauth_nonce="a9900fe68e2573b27a37f10fbad6a755",
                          oauth_signature="39cipBtIOHEEnybAR4sATQTpl2I%3D",
                          oauth_signature_method="HMAC-SHA1",
                          oauth_timestamp="1318467427",
                          oauth_token="NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0",
                          oauth_version="1.0"
    Content-Length: 57
    Content-Type: application/x-www-form-urlencoded

    oauth_verifier=uw7NjWHT6OJ1MpJOXsHfNxoAhPKpgI8BlYDhxEjIBY
    ```

    A successful response contains the oauth\_token, oauth\_token\_secret parameters. The token and token secret should be stored and used for future authenticated requests to the X API. To determine the identity of the user, use [GET account/verify\_credentials](https://dev.x.com/rest/reference/get/account/verify_credentials).

    **Example response (response body has been wrapped):**

    ```
    HTTP/1.1 200 OK
    Date: Thu, 13 Oct 2011 00:57:08 GMT
    Status: 200 OK
    Content-Type: text/html; charset=utf-8
    Content-Length: 157
    Pragma: no-cache
    Expires: Tue, 31 Mar 1981 05:00:00 GMT
    Cache-Control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0
    Vary: Accept-Encoding
    Server: tfe

    oauth_token=7588892-kagSNqWge8gB1WwE3plnFsJHAZVfxWD7Vb57p0b4&
    oauth_token_secret=PbKfYqSryyeKDWz4ebtY3o5ogNLG11WJuZBc9fQrQo
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Additional resources">
    ### Log in with X Resources

    #### Client libraries

    The client libraries listed at [X libraries](/resources/tools-and-libraries) will help implement Log in with X. Use the /oauth/authenticate endpoint, as described in the previous steps.

    #### Brand Toolkit

    X would prefer your application to use the official [X Brand Toolkit](https://about.x.com/en/who-we-are/brand-toolkit) for consistent branding. Save these assets and use them when creating a 'Login with X' button.
  </Tab>

  <Tab title="Browser sign in flow">
    The browser log in flow is appropriate for websites and applications which are able to open or embed a web browser. At a very high level:

    * The application renders a “Sign in with X” link or button.
    * The user clicks the sign in button.
    * The current web browser is redirected to X (or a new browser is opened and directed to X).
    * The user completes a login and authorization step at X if needed.
    * X redirects back to an URL under the application’s control, passing authorization information for the user.

    X keeps track of the authorizations, so for users already signed in to X.com who have authorized the application, no UI is shown - instead, they are automatically redirected back to the application.

    ### Desktop flow

    <Frame>
      <img alt="" />
    </Frame>

    To demonstrate the flows, pretend the website pictured above (“The greatest website ever created”) has implemented this API, as shown by the Sign in with X button on the landing page.

    When the user clicks the Sign in button, the page they see depends on whether they are signed in and whether they have previously allowed the application to access their account.

    When the user is signed in to x.com but has not granted access, a list of requested permissions, along with Sign In and Cancel buttons are shown.

    When the user is not signed in to x.com input fields for a username and password will be shown. Note that even if the user has already granted access to the application, the list of permissions will still be shown.

    <Frame>
      <img alt="" />
    </Frame>

    <Frame>
      <img alt="" />
    </Frame>

    <Frame>
      <img alt="" />
    </Frame>

    After the user inputs valid credentials (if needed) and clicks “Sign In”, X will redirect the user to the website which started the sign in flow.

    In the case where the user is already signed in to x.com and has granted access to the website, this redirect happens immediately.
  </Tab>

  <Tab title="Mobile sign in flow">
    The UI flow for mobile web browsers works exactly like the Browser sign in flow, but is optimized for mobile browsers.

    Below are screenshots for the signed in, signed out, and redirect screens:

    <Frame>
      <img alt="Mobile sign in flow" />
    </Frame>
  </Tab>
</Tabs>


# Connection to X API using TLS
Source: https://docs.x.com/fundamentals/authentication/guides/tls

Connect securely to the X API over TLS 1.2, with guidance on trusted root stores, certificate revocation checks, and HTTPS verification practices.

TLS connections are required in order to access X API endpoints. Communicating over TLS preserves user privacy and security by protecting information between the user and the X API as it travels across the public Internet. Connections to the X API require TLS version 1.2.

## Verification

### Use an up-to-date root store

It's important that your application or library use a trustworthy and up-to-date root store when verifying the X certificate. Where possible, using the root store provided by your operating system may be the simplest approach here. Alternatively, the [Mozilla (NSS) root store](https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/) is well maintained in a public and transparent manner. Curl also provides [a version of this store in PEM format](https://curl.haxx.se/docs/caextract.html).

X currently issues the bulk of our certs from the [DigiCert High Assurance EV Root CA](https://www.digicert.com/digicert-root-certificates.htm), but this is not true for 100% of X-related certificates and may not hold true forever, so trusting only the currently-used Digicert roots may lead to issues with your app in the future.

### Check CRLs and the OCSP status[](#check-crls-and-the-ocsp-status "Permalink to this headline")

Many applications do not check the Certificate Revocation List for returned certificates or rely on the operating system to do so. Ensure that your application or TLS library is configured to force CRL and OCSP (Online Certificate Status Protocol) verification before accepting X’s certificate.

### CDNs[](#cdns "Permalink to this headline")

When showing Tweets that contain media, use the `media_url_https` attribute for the HTTPS URLs to use when showing images. In the future, all URLs served from API endpoints will provide HTTPS paths.

## Provide an indication of security status

If possible, you should show an indication of the current status between your application and X. Some web browsers indicate this by offering a Lock Icon, while others indicate the current connection state with descriptive messaging.


# X API v2 authentication mapping
Source: https://docs.x.com/fundamentals/authentication/guides/v2-authentication-mapping

The following chart illustrates which v2 endpoints map to what authentication methods. Documentation for the X developer platform covering v2 authentication.

The following chart illustrates which v2 endpoints map to what authentication methods. 
 

|                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                             |                                     |                                                                                                                                              |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| **Endpoint**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | **OAuth 1.0a User Context** | **OAuth 2.0** **App Only   <br />** | **OAuth 2.0  <br />Authorization Code with PKCE**                                                                                            |
| [Tweet lookup](/x-api/posts/lookup/introduction)<br /><br />Retrieve multiple Tweets with a list of IDs<br /><br />[GET /2/tweets](/x-api/posts/post-lookup-by-post-ids)<br /><br />Retrieve a single Tweet with an ID<br /><br />[GET /2/tweets/:id](/x-api/posts/post-lookup-by-post-id)                                                                                                                                                                                                                                                                                                                                                        | ✅                           | ✅                                   | ✅  <br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read                                                                           |
| [Manage Tweets](/x-api/posts/manage-tweets/introduction)<br /><br />Post a Tweet<br /><br />[POST /2/tweets](/x-api/posts/creation-of-a-post)<br /><br />Delete a Tweet<br /><br />[DELETE /2/tweets/:id](/x-api/posts/post-delete-by-post-id)                                                                                                                                                                                                                                                                                                                                                                                                    | ✅                           |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />tweet.write<br /><br />users.read                                                      |
| [Timelines](/x-api/posts/timelines/introduction)<br /><br />User Tweet timeline<br /><br />[GET /2/users/:id/tweets](/x-api/users/get-posts)<br /><br />User mention timeline<br /><br />[GET /2/users/:id/mentions](/x-api/users/get-mentions)<br /><br />Reverse chronological home timeline<br /><br />[GET /2/users/:id/timelines/reverse\_cronological](/x-api/posts/timelines#user-mention-timeline-3)                                                                                                                                                                                                                                      | ✅<br /><br />✅              | ✅                                   | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read |
| [Recent search](/x-api/posts/search/introduction#recent-search)<br /><br />Search for Tweets published in the last 7 days<br /><br />[GET /2/tweets/search/recent](/x-api/posts/recent-search)                                                                                                                                                                                                                                                                                                                                                                                                                                                    | ✅                           | ✅                                   | ✅<br /><br />Scopes: <br /><br />tweet.read<br /><br />users.read                                                                            |
| [Full-archive search](/x-api/posts/search/introduction#full-archive-search)<br /><br />Only available to those with Academic Research access<br /><br />Search the full archive of Tweets<br /><br />[GET /2/tweets/search/all](/x-api/posts/full-archive-search)                                                                                                                                                                                                                                                                                                                                                                                 |                             | ✅                                   |                                                                                                                                              |
| [Filtered stream](/x-api/posts/filtered-stream/introduction)<br /><br />Add or delete rules from your stream<br /><br />[POST /2/tweets/search/stream/rules](/x-api/stream/update-stream-rules)<br /><br />Retrieve your stream's rules<br /><br />[GET /2/tweets/search/stream/rules](/x-api/stream/get-stream-rules)<br /><br />Connect to the stream<br /><br />[GET /2/tweets/search/stream](/x-api/posts/filtered-stream)                                                                                                                                                                                                                    |                             | ✅                                   |                                                                                                                                              |
| [Volume streams](/x-api/posts/volume-streams/introduction)<br /><br />Streams about 1% of all Tweets in real-time.<br /><br />[GET /2/tweets/sample/stream](/x-api/stream/stream-sampled-posts)                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                             | ✅                                   |                                                                                                                                              |
| [Manage Retweets](/x-api/posts/retweets/introduction#manage-retweets)<br /><br />Retweet a Tweet<br /><br />[POST /2/users/:id/retweets](/x-api/posts/retrieve-posts-that-repost-a-post)<br /><br />Delete a Retweet<br /><br />[DELETE /2/users/:id/retweets/:source\_tweet\_id](/x-api/users/unrepost-post)                                                                                                                                                                                                                                                                                                                                     | ✅                           |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />tweet.write<br /><br />users.read                                                      |
| [Retweets lookup](/x-api/posts/retweets/introduction#retweets-lookup)<br /><br />Users who have Retweeted a Tweet<br /><br />[GET /2/tweets/:id/retweeted\_by](/x-api/posts/get-reposted-by)                                                                                                                                                                                                                                                                                                                                                                                                                                                      | ✅                           | ✅                                   | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read                                                                             |
| Bookmarks [lookup](/x-api/posts/bookmarks/introduction#bookmarks-lookup)<br /><br />Get bookmarked Tweets<br /><br />[GET /2/tweets/:id/bookmarks](/x-api/bookmarks/bookmarks-by-user)                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                             |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />bookmark.read                                                    |
| [Manage Bookmarks](/x-api/posts/bookmarks/introduction#manage-bookmarks)<br /><br />Bookmark a Tweet<br /><br />[POST /2/tweets/:id/bookmarks](/x-api/bookmarks/add-post-to-bookmarks)<br /><br />Remove a Bookmark of a Tweet<br /><br />[DELETE /2/users/:id/bookmarks:tweet\_id](/x-api/bookmarks/remove-a-bookmarked-post)                                                                                                                                                                                                                                                                                                                    |                             |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />bookmark.write                                                   |
| [Manage Likes](/x-api/posts/likes/introduction#manage-likes)<br /><br />Like a Tweet<br /><br />[POST /2/users/:id/likes](/x-api/users/like-post)<br /><br />Undo a Like of a Tweet<br /><br />[DELETE /2/users/:id/likes/:tweet\_id](/x-api/users/unlike-post)                                                                                                                                                                                                                                                                                                                                                                                   | ✅                           |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />like.write                                                       |
| [Likes lookup](/x-api/posts/likes/introduction#likes-lookup)<br /><br />Users who have liked a Tweet<br /><br />[GET /2/tweets/:id/liking\_users](/x-api/posts/get-liking-users)<br /><br />Tweets liked by a user<br /><br />[GET /2/users/:id/liked\_tweets](/x-api/users/get-liked-posts)                                                                                                                                                                                                                                                                                                                                                      | ✅                           | ✅                                   | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />like.read                                                        |
| [Hide replies](/x-api/posts/hide-replies/introduction)<br /><br />Hides or unhides a reply to a Tweet.<br /><br />[PUT /2/tweets/:id/hidden](/x-api/posts/hide-replies)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | ✅                           |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />tweet.moderate.write                                             |
| [Users lookup](/x-api/users/lookup/introduction)<br /><br />Retrieve multiple users with IDs<br /><br />[GET /2/users](/x-api/users/user-lookup-by-ids)<br /><br />Retrieve a single user with an ID<br /><br />[GET /2/users/:id](/x-api/users/user-lookup-by-id)<br /><br />Retrieve multiple users with usernames<br /><br />[GET /2/users/by](/x-api/users/user-lookup-by-usernames)<br /><br />Retrieve a single user with a username<br /><br />[GET /2/users/by/username/:username](/x-api/users/user-lookup-by-username)<br /><br />Get information about an authenticated user<br /><br />[GET /2/users/me](/x-api/users/user-lookup-me) | ✅                           | ✅                                   | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read                                                                             |
| [Manage follows](/x-api/users/follows/introduction#manage-follows)<br /><br />Allows a user ID to follow another user<br /><br />[POST /2/users/:id/following](/x-api/users/follow-user)<br /><br />Allows a user ID to unfollow another user<br /><br />[DELETE /2/users/:source\_user\_id/following/:target\_user\_id](/x-api/users/unfollow-user)                                                                                                                                                                                                                                                                                              | ✅                           |                                     | ✅<br /><br />Scopes: <br /><br />tweet.read<br /><br />users.read<br /><br />follows.write                                                   |
| [Follows lookup](/x-api/users/follows/introduction#follows-lookup)<br /><br />Lookup following of a user by ID<br /><br />[GET /2/users/:id/following](/x-api/users/following-by-user-id)<br /><br />Lookup followers of a user by ID<br /><br />[GET /2/users/:id/followers](/x-api/users/followers-by-user-id)                                                                                                                                                                                                                                                                                                                                  | ✅                           | ✅                                   | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />follows.read                                                     |
| [Blocks lookup](/x-api/users/blocks/introduction#blocks-lookup)<br /><br />Returns a list of users who are blocked by the specified user ID <br /><br />[GET /2/users/:id/blocking](/x-api/users/returns-user-objects-that-are-blocked-by-provided-user-id)                                                                                                                                                                                                                                                                                                                                                                                       | ✅                           |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />block.read                                                       |
| [Manage Mutes](/x-api/users/mutes/introduction#manage-mutes)<br /><br />Allows a user ID to mute another user<br /><br />[POST /2/users/:id/muting](/x-api/users/mute-user-by-user-id)<br /><br />Allows a user ID to unmute another user<br /><br />[DELETE /2/users/:source\_user\_id/muting/:target\_user\_id](/x-api/users/unmute-user-by-user-id)                                                                                                                                                                                                                                                                                            | ✅                           |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />mute.write                                                       |
| [Mutes lookup](/x-api/users/mutes/introduction#mutes-lookup)<br /><br />Returns a list of users who are muted by the specified user ID<br /><br />[GET /2/users/:id/muting](/x-api/users/returns-user-objects-that-are-muted-by-the-provided-user-id)                                                                                                                                                                                                                                                                                                                                                                                             | ✅                           |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />mute.read                                                        |
| [Spaces lookup](/x-api/spaces/lookup/introduction)<br /><br />Lookup Space by ID<br /><br />[GET /2/spaces/:id](/x-api/spaces/space-lookup-by-space-id)<br /><br />Lookup multiple Spaces <br /><br />[GET /2/spaces](/x-api/spaces/space-lookup-up-space-ids)<br /><br />Discover Spaces created by user ID<br /><br />[GET /2/spaces/by/creator\_ids](/x-api/spaces/space-lookup-by-their-creators)                                                                                                                                                                                                                                             |                             | ✅                                   | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />space.read                                                       |
| [Spaces lookup](/x-api/spaces/lookup/introduction)<br /><br />Get users who purchased a ticket to a Space<br /><br />[GET /2/spaces/:id/buyers](/x-api/spaces/retrieve-the-list-of-users-who-purchased-a-ticket-to-the-given-space)                                                                                                                                                                                                                                                                                                                                                                                                               |                             |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />space.read                                                       |
| [Spaces search](/x-api/spaces/search/introduction)<br /><br />Returns live or scheduled Spaces matching your specified search terms.<br /><br />[GET /2/spaces/search](/x-api/spaces/search-for-spaces)                                                                                                                                                                                                                                                                                                                                                                                                                                           |                             | ✅                                   | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />space.read                                                       |
| [List lookup](/x-api/lists/list-lookup/introduction)<br /><br />Lookup a specific list by ID<br /><br />[GET /2/lists/:id](/x-api/lists/list-lookup-by-list-id)<br /><br />Lookup a user's owned List<br /><br />[GET /2/users/:id/owned\_lists](/x-api/users/get-owned-lists)                                                                                                                                                                                                                                                                                                                                                                    | ✅                           | ✅                                   | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />list.read                                                        |
| [Manage Lists](/x-api/lists/manage-lists/introduction)<br /><br />Creates a new List on behalf of an authenticated user<br /><br />[POST /2/lists](/x-api/lists/create-list)                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | ✅                           |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />list.read<br /><br />list.write                                  |
| [Manage Lists](/x-api/lists/manage-lists/introduction)<br /><br />Deletes a List the authenticated user owns<br /><br />[DELETE /2/lists/:id](/x-api/lists/delete-list)<br /><br />Updates the metadata for a List the authenticated user owns<br /><br />[PUT /2/lists/:id](/x-api/lists/update-list)                                                                                                                                                                                                                                                                                                                                            | ✅                           |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />list.write                                                       |
| [List Tweets lookup](/x-api/lists/list-tweets/introduction)<br /><br />Lookup Tweets from a specified List<br /><br />[GET /2/lists/:id/tweets](/x-api/lists/get-list-posts)                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | ✅                           | ✅                                   | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />list.read                                                        |
| [List members lookup](/x-api/lists/list-members/introduction#list-members-lookup)<br /><br />Returns a list of members from a specified List<br /><br />[GET /2/lists/:id/members](/x-api/lists/get-list-members)<br /><br />Returns all Lists a specified user is a member of<br /><br />[GET /2/users/:id/list\_memberships](/x-api/users/get-list-memberships)                                                                                                                                                                                                                                                                                 | ✅                           | ✅                                   | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />list.read                                                        |
| [Manage List members](/x-api/lists/list-members/introduction#manage-list-members)<br /><br />Add a member to a List that the authenticated user owns<br /><br />[POST /2/lists/:id/members](/x-api/lists/add-list-member)<br /><br />Removes a member from a List the authenticated user owns<br /><br />[DELETE /2/lists/:id/members/:user\_id](/x-api/lists/remove-a-list-member)                                                                                                                                                                                                                                                               | ✅                           |                                     | ✅<br /><br />Scopes:<br /><br />tweet.read<br /><br />users.read<br /><br />list.write                                                       |
| [List follows lookup](/x-api/lists/list-lookup/introduction)<br /><br />Returns all followers of a specified List<br /><br />[GET /2/lists/:id/followers](/x-api/lists/get-list-followers)<br /><br />Returns all Lists a specified user follows<br /><br />[GET /2/users/:id/followed\_lists](/x-api/users/get-followed-lists)                                                                                                                                                                                                                                                                                                                   | ✅                           | ✅                                   | ✅<br /><br />Scope                                                                                                                           |


# API Key and Secret
Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/api-key-and-secret

Learn what the X API Key and Secret (consumer key and secret) are, how to create them in the Developer Portal, and how to regenerate or rotate them.

### API Key and Secret

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 as the username and password for your X App, and are used by the X API to understand which App requests are coming from. 

These credentials can be used by [authentication endpoints](/resources/fundamentals/authentication/api-reference) to generate additional credentials, such as [user Access Tokens and Secrets](/resources/fundamentals/authentication/oauth-1-0a/api-key-and-secret), and [Bearer Tokens](/resources/fundamentals/authentication/oauth-2-0/bearer-tokens). You also need to use these credentials along with Access Tokens and other authorization parameters to [authorize requests](/resources/fundamentals/authentication/oauth-1-0a/authorizing-a-request) that require OAuth 1.0a User Context authentication. 

#### How to acquire an API Key and Secret

To acquire a X API Key and Secret, please follow these steps:

1. [Sign up for a X developer account](https://developer.x.com/en/apply-for-access)
2. Create a [X App](/resources/fundamentals/developer-apps) within the [Developer Console](/resources/fundamentals/developer-portal). Note that if you would like to use [X API v2](/x-api/introduction), you must use keys and tokens from a developer App.
    

When you create your X App, you will be presented with your API Key and Secret, along with a Bearer Token. Please note that we only display these credentials once, so make sure to save them in your password manager or somewhere secure.

We have more recommendations on how to handle your keys and tokens within our [authentication best practices](/resources/fundamentals/authentication/guides/authentication-best-practices) page, including details on what you should do if your credentials have been compromised.
 

#### How to find and regenerate your API Key and Secret after App creation

If you've already created an App and need to find or regenerate your API Key and Secret, please follow these steps:

1. Navigate to the Developer Console
2. Expand the 'Apps' dropdown in the sidenav
3. Open the App which is associated with the API Key and Secret that you would like to find or regenerate
4. Navigate to the Keys and tokens tab

From there, you will find all of the credentials associated with your App. 
 

#### How to use your API Key and Secret

If you are just exploring the X Developer Platform, we recommend that you use a [tool or library](/resources/tools-and-libraries) to see what’s available on the platform. These tools handle authentication gracefully, and can save you a lot of time and frustration. We specifically recommend [getting started with Postman](/tutorials/postman-getting-started) or [Insomnia](https://insomnia.rest/) for beginner developers. 

If you are interested in building a request from scratch, please read our guide on [authorizing an OAuth 1.0a request](/resources/fundamentals/authentication/oauth-1-0a/authorizing-a-request).
 


# Authorizing a request
Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/authorizing-a-request

Build an OAuth 1.0a Authorization header to sign X API requests, including the consumer key, nonce, signature, timestamp, token, and version fields.

### Authorizing a request

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 based on the HTTP protocol. This means that any software you write which uses X's APIs sends a series of structured messages to X’s servers. For example, a request to post the text “**Hello Ladies + Gentlemen, a signed OAuth request!**” as a Tweet will look something like this:

```
POST /1.1/statuses/update.json?include_entities=true HTTP/1.1
Accept: */*
Connection: close
User-Agent: OAuth gem v0.4.4
Content-Type: application/x-www-form-urlencoded
Content-Length: 76
Host: api.x.com

status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21
```

Any HTTP library should be able to generate and issue the above request with a minimum of difficulty. However, the above request is considered invalid, since there is no way of knowing:

1. Which application is making the request
2. Which user the request is posting on behalf of
3. Whether the user has granted the application authorization to post on the user’s behalf
4. Whether the request has been tampered by a third party while in transit

To allow applications to provide this information, X’s API relies on the [OAuth 1.0a protocol](http://tools.ietf.org/html/rfc5849). At a very simplified level, X’s implementation requires that requests needing authorization contain an additional HTTP Authorization header with enough information to answer the questions listed above. A version of the HTTP request shown above, modified to include this header, looks like this (normally the Authorization header would need to be on one line, but has been wrapped for legibility here):

```
POST /1.1/statuses/update.json?include_entities=true HTTP/1.1
Accept: */*
Connection: close
User-Agent: OAuth gem v0.4.4
Content-Type: application/x-www-form-urlencoded
Authorization:
OAuth oauth\_consumer\_key="xvz1evFS4wEEPTGEFPHBog",
oauth_nonce="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg",
oauth_signature="tnnArxj06cWHq44gCs1OSKk%2FjLY%3D",
oauth\_signature\_method="HMAC-SHA1",
oauth_timestamp="1318622958",
oauth_token="370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb",
oauth_version="1.0"
Content-Length: 76
Host: api.x.com

status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21
```

When this request was created, it would have been accepted by the X API as valid.

If this signing process sounds like it is beyond the scope of your integration, consider using [Web Intents](https://dev.x.com/web/intents), which do not need to use OAuth to interact with the X API.
 

**Collecting parameters**

You should be able to see that the header contains 7 key/value pairs, where the keys all begin with the string “oauth\_”. For any given X API request, collecting these 7 values and creating a similar header will allow you to specify authorization for the request. How each value was generated is described below:

**Consumer key**

The oauth\_consumer\_key identifies which application is making the request. Obtain this value from the settings page for your [X app](/resources/fundamentals/developer-apps) in the [Developer Console](/resources/fundamentals/developer-portal).

|                      |                        |
| :------------------- | :--------------------- |
| oauth\_consumer\_key | xvz1evFS4wEEPTGEFPHBog |

**Nonce**

The oauth\_nonce parameter is a unique token your application should generate for each unique request. X will use this value to determine whether a request has been submitted multiple times. The value for this request was generated by base64 encoding 32 bytes of random data, and stripping out all non-word characters, but any approach which produces a relatively random alphanumeric string should be OK here.

|              |                                            |
| :----------- | :----------------------------------------- |
| oauth\_nonce | kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg |

**Signature**

The oauth\_signature parameter contains a value which is generated by running all of the other request parameters and two secret values through a signing algorithm. The purpose of the signature is so that X can verify that the request has not been modified in transit, verify the application sending the request, and verify that the application has authorization to interact with the user’s account.

The process for calculating the oauth\_signature for this request is described in [Creating a signature](/resources/fundamentals/authentication/oauth-1-0a/creating-a-signature).

|                  |                              |
| :--------------- | :--------------------------- |
| oauth\_signature | tnnArxj06cWHq44gCs1OSKk/jLY= |

**Signature method**

The oauth\_signature\_method used by X is HMAC-SHA1. This value should be used for any authorized request sent to X’s API.

|                          |           |
| :----------------------- | :-------- |
| oauth\_signature\_method | HMAC-SHA1 |

**Timestamp**

The oauth\_timestamp parameter indicates when the request was created. This value should be the number of seconds since the Unix epoch at the point the request is generated, and should be easily generated in most programming languages. X will reject requests which were created too far in the past, so it is important to keep the clock of the computer generating requests in sync with NTP.

|                  |            |
| :--------------- | :--------- |
| oauth\_timestamp | 1318622958 |

**Token**

The oauth\_token parameter typically represents a user’s permission to share access to their account with your application. There are a few authentication requests where this value is not passed or is a different form of token, but those are covered in detail in [Obtaining access tokens](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens). For most general-purpose requests, you will use what is referred to as an **access token**.

You can generate a valid [access token](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) for your account on the settings page for your [X app](/resources/fundamentals/developer-apps) on the [Developer Console](/resources/fundamentals/developer-portal).

|              |                                                    |
| :----------- | :------------------------------------------------- |
| oauth\_token | 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb |

**Version**

The oauth\_version parameter should always be 1.0 for any request sent to the X API.

|                |     |
| :------------- | :-- |
| oauth\_version | 1.0 |

#### Building the header string

To build the header string, imagine writing to a string named DST.

1. Append the string “OAuth ” (including the space at the end) to DST.
2. For each key/value pair of the 7 parameters listed above:
   1. [Percent encode](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) the key and append it to DST.
   2. Append the equals character ‘=’ to DST.
   3. Append a double quote ‘”’ to DST.
   4. [Percent encode](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) the value and append it to DST.
   5. Append a double quote ‘”’ to DST.
   6. If there are key/value pairs remaining, append a comma ‘,’ and a space ‘ ‘ to DST.

Pay particular attention to the percent encoding of the values when building this string. For example, the oauth\_signature value of tnnArxj06cWHq44gCs1OSKk/jLY= must be encoded as tnnArxj06cWHq44gCs1OSKk%2FjLY%3D.

Performing these steps on the parameters collected above results in the following string:

```
OAuth oauth\_consumer\_key="xvz1evFS4wEEPTGEFPHBog", oauth\_nonce="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg", oauth\_signature="tnnArxj06cWHq44gCs1OSKk%2FjLY%3D", oauth\_signature\_method="HMAC-SHA1", oauth\_timestamp="1318622958", oauth\_token="370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb", oauth_version="1.0"
```

This value should be set as the Authorization header for the request.


# Creating a signature
Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/creating-a-signature

Generate an OAuth 1.0a HMAC-SHA1 signature for X API requests by collecting parameters, building the signature base string, and signing with your keys.

### Creating a signature

This page explains how to generate an OAuth 1.0a HMAC-SHA1 signature for an HTTP request. This signature will be suitable for passing to the X API as part of an authorized request, as described in [authorizing a request.](/resources/fundamentals/authentication/oauth-1-0a/authorizing-a-request)

The request used to demonstrate signing is a POST to [https://api.x.com/1.1/statuses/update.json](https://api.x.com/1.1/statuses/update.json). The raw request looks like this:

```
POST /1.1/statuses/update.json?include_entities=true HTTP/1.1
Accept: */*
Connection: close
User-Agent: OAuth gem v0.4.4
Content-Type: application/x-www-form-urlencoded
Content-Length: 76
Host: api.x.com

status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21
```

**Collecting the request method and URL**

To produce a signature, start by determining the HTTP method and URL of the request. These two are known when creating the request, so they are easy to obtain.

The request method will almost always be GET or POST for X API requests.

|             |      |
| :---------- | :--- |
| HTTP Method | POST |

The base URL is the URL to which the request is directed, minus any query string or hash parameters. It is important to use the correct protocol here, so make sure that the “https\://” portion of the URL matches the actual request sent to the API.

|          |                                                                                          |
| :------- | :--------------------------------------------------------------------------------------- |
| Base URL | [https://api.x.com/1.1/statuses/update.json](https://api.x.com/1.1/statuses/update.json) |

#### Collecting parameters

Next, gather all of the parameters included in the request. There are two such locations for these additional parameters - the URL (as part of the query string) and the request body. The sample request includes a single parameter in both locations:

```
POST /1.1/statuses/update.json?include_entities=true HTTP/1.1
Accept: */*
Connection: close
User-Agent: OAuth gem v0.4.4
Content-Type: application/x-www-form-urlencoded
Content-Length: 76
Host: api.x.com

status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21
```

An HTTP request has parameters that are URL encoded, but you should collect the raw values. In addition to the request parameters, every oauth\_\* parameter needs to be included in the signature, so collect those too. Here are the parameters from [authorizing a request](/resources/fundamentals/authentication/oauth-1-0a/authorizing-a-request):

|                          |                                                    |
| :----------------------- | :------------------------------------------------- |
| status                   | Hello Ladies + Gentlemen, a signed OAuth request!  |
| include\_entities        | true                                               |
| oauth\_consumer\_key     | xvz1evFS4wEEPTGEFPHBog                             |
| oauth\_nonce             | kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg         |
| oauth\_signature\_method | HMAC-SHA1                                          |
| oauth\_timestamp         | 1318622958                                         |
| oauth\_token             | 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb |
| oauth\_version           | 1.0                                                |

These values need to be encoded into a single string, which will be used later on. The process to build the string is very specific:

1. [Percent encode](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters) every key and value that will be signed.
2. Sort the list of parameters alphabetically [\[1\]](/resources/fundamentals/authentication/oauth-1-0a/creating-a-signature) by encoded key [\[2\]](/resources/fundamentals/authentication/oauth-1-0a/creating-a-signature).
3. For each key/value pair:
4. Append the encoded key to the output string.
5. Append the ‘=’ character to the output string.
6. Append the encoded value to the output string.
7. If there are more key/value pairs remaining, append a ‘&’ character to the output string.
    

\[1] The OAuth spec says to sort lexicographically, which is the default alphabetical sort for many libraries.

\[2] In the case of two parameters with the same encoded key, the OAuth spec says to continue sorting based on value. However, X does not accept duplicate keys in API requests
 

**Parameter string**

The following *parameter string* will be produced by repeating these steps with the parameters collected above:

| status                   | Hello Ladies + Gentlemen, a signed OAuth request!  |
| :----------------------- | :------------------------------------------------- |
| `include_entities`       | true                                               |
| `oauth_consumer_key`     | xvz1evFS4wEEPTGEFPHBog                             |
| `oauth_nonce`            | kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg         |
| `oauth_signature_method` | HMAC-SHA1                                          |
| `oauth_timestamp`        | 1318622958                                         |
| `oauth_token`            | 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb |
| `oauth_version`          | 1.0                                                |

#### Creating the signature base string

The three values collected so far must be joined to make a single string, from which the signature will be generated. This is called the **signature base string** by the OAuth specification.

To encode the HTTP method, base URL, and parameter string into a single string:

1. Convert the HTTP Method to uppercase and set the output string equal to this value.
2. Append the ‘&’ character to the output string.
3. [Percent encode](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters) the URL and append it to the output string.
4. Append the ‘&’ character to the output string.
5. [Percent encode](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters) the parameter string and append it to the output string.
    

This will produce the following *signature base string*:

```
POST&https%3A%2F%2Fapi.x.com%2F1.1%2Fstatuses%2Fupdate.json&include_entities%3Dtrue%26oauth_consumer_key%3Dxvz1evFS4wEEPTGEFPHBog%26oauth_nonce%3DkYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1318622958%26oauth_token%3D370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb%26oauth_version%3D1.0%26status%3DHello%2520Ladies%2520%252B%2520Gentlemen%252C%2520a%2520signed%2520OAuth%2520request%2521
```

Make sure to percent encode the parameter string. The signature base string should contain exactly 2 ampersand ‘&’ characters. The percent ‘%’ characters in the parameter string should be encoded as %25 in the signature base string.
 

#### Getting a signing key

The last pieces of data to collect are secrets which identify the [X app](/resources/fundamentals/developer-apps) making the request, and the user the request is on behalf of. It is very important to note that these values are incredibly sensitive and should never be shared with anyone.

The value which identifies your app to X is called the **consumer secret** and can be found in the [Developer Console](/resources/fundamentals/developer-portal) by viewing the [app details page](/resources/fundamentals/developer-apps). This will be the same for every request your X app sends.

|                 |                                             |
| :-------------- | :------------------------------------------ |
| Consumer secret | kAcSOqF21Fu85e7zjz7ZN2U4ZRhfV3WpwPAoE3Z7kBw |

The value which identifies the account your application is acting on behalf of is called the **OAuth token secret**. This value can be obtained in several ways, all of which are described in [obtaining access tokens](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens).

|                    |                                           |
| :----------------- | :---------------------------------------- |
| OAuth token secret | LswwdoUaIvS8ltyTt5jkRh4J50vUPVVHtR2YPi5kE |

Once again, it is very important to keep these values private to your application. If you feel that your values have been compromised, regenerate your tokens (the tokens on this page have been marked as invalid for real requests).

Both of these values need to be combined to form a **signing key** which will be used to generate the signature. The signing key is simply the [percent encoded](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters) token secret:

Note that there are some flows, such as when obtaining a [request token](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens), where the token secret is not yet known. In this case, the signing key should consist of the [percent encoded](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters) **consumer secret** followed by an ampersand character ‘&’.

|             |                                                                                        |
| :---------- | :------------------------------------------------------------------------------------- |
| Signing key | kAcSOqF21Fu85e7zjz7ZN2U4ZRhfV3WpwPAoE3Z7kBw\&LswwdoUaIvS8ltyTt5jkRh4J50vUPVVHtR2YPi5kE |

#### Calculating the signature

Finally, the signature is calculated by passing the signature base string and signing key to the HMAC-SHA1 hashing algorithm. The details of the algorithm are explained as hash\_hmac function.

The output of the HMAC signing function is a binary string. This needs to be base64 encoded to produce the signature string. For example, the output given the base string and signing key given on this page is 2E CF 77 84 98 99 6D 0D DA 90 5D C7 17 7C 75 07 3F 3F CD 4E. That value, when converted to base64, is the OAuth signature for this request:

|                 |                              |
| :-------------- | :--------------------------- |
| OAuth signature | Ls93hJiZbQ3akF3HF3x1Bz8/zU4= |


# OAuth Echo
Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/oauth-echo

Use OAuth Echo to securely delegate X authentication to a third party media provider for uploads using x-auth-service-provider and verify-credentials headers.

### OAuth Echo

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

* **the User** who is using X through a particular, authorized X application
* **the Consumer**, or the X application that is attempting to interact with the 3rd party media provider (e.g. the photo-sharing site)
* **the Delegator**, or the 3rd party media provider
* **the Service Provider** a.k.a. X itself
   

Essentially, prepare a request for the delegator to send to the X API on behalf of an application and a user. Add what would otherwise be a signed OAuth request into an HTTP header and ask the delegator to send that request to X after completing the intermediary operation.

Here’s an example: the User wants to upload a photo. The Consumer is going to call upload on the Delegator with a POST. The POST should contain the image, but it should also contain two additional items as HTTP headers:

* `x-auth-service-provider` — effectively, this is the realm that identity delegation should be sent to — in the case of X, set this to [https://api.x.com/1.1/account/verify\_credentials.json](https://api.x.com/1.1/account/verify_credentials.json). iOS5-based X integrations will add an additional application\_id parameter to this URL that will also be used to calculate the oauth\_signature used in x-verify-credentials-authorization.
* `x-verify-credentials-authorization` — Consumer should create all the OAuth parameters necessary so it could call [https://api.x.com/1.1/account/verify\_credentials.json](https://api.x.com/1.1/account/verify_credentials.json) using OAuth in the HTTP header (e.g. it should look like OAuth oauth\_consumer\_key=”...”, oauth\_token=”...”, oauth\_signature\_method=”...”, oauth\_signature=”...”, oauth\_timestamp=”...”, oauth\_nonce=”...”, oauth\_version=”...” ).
   

Keep in mind that the entire transaction period needs to occur within an amount of time where the `oauth_timestamp` will still be valid.

Alternatively, instead of sending these two parameters in the header, they could be sent in the POST as x\_auth\_service\_provider and x\_verify\_credentials\_authorization — in this case, remember to escape and include the parameters in the OAuth signature base string — similar to encoding parameters in any request. It’s best to use HTTP headers to keep the operations as separate as possible.

The Delegator’s goal, at this point, is to verify that the User is who they say they are before it saves the media. Once the Delegator receives all the data above via its upload method, it should temporarily store the image, and then construct a call to the endpoint specified in the x-auth-service-provider header — in this case, [https://api.x.com/1.1/account/verify\_credentials.json](https://api.x.com/1.1/account/verify_credentials.json), using the same OAuth authentication header provided by the Consumer in the x-verify-credentials-authorization header.
 

#### OAuth Echo best practices

Use the URL provided by `x-auth-service-provider` to perform the lookup, *not* a hard-coded value. Apple iOS, for example, adds an additional application\_id parameter to all OAuth requests, and its existence should be maintained at each stage of OAuth Echo.

For the OAuth authorization portion, take the header value in x-verify-credentials-authorization, and place that into its own Authorization header for its call to the service provider. For good measure, confirm that the value in `x-auth-service-provider` is what it should be.

* If the Service Provider returns an HTTP 200, then good. The Delegator should permanently store the image, generate a URL, and return it.
* If the Service Provider doesn’t return an HTTP 200, then dump the image, and then return an error back to the Consumer.


# Obtaining Access Tokens using 3-legged OAuth flow
Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens

Walk through the 3-legged OAuth 1.0a flow to obtain user access tokens for the X API using request_token, authorize, and access_token endpoints.

### Obtaining access tokens using 3-legged OAuth flow

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 behalf of, so for you to obtain these they will need to first grant you access. These tokens do not expire but can be revoked by the user at any time.

X allows you to obtain user access tokens through the 3-legged OAuth flow, which allows your application to obtain an **access token** and access token secret by redirecting a user to X and having them authorize your application. This flow is almost identical to the flow described in [implementing Log in with X](/resources/fundamentals/authentication/guides/log-in-with-x), with two exceptions:

* The [GET oauth/authorize](/resources/fundamentals/authentication/api-reference#get-oauth-authorize) endpoint is used instead of [GET oauth/authenticate](/resources/fundamentals/authentication/api-reference#get-oauth-authenticate).
* The user will **always** be prompted to authorize access to your application, even if access was previously granted.
   

Before you get started, you will need to check your [application's](/resources/fundamentals/developer-apps) permissions and know the consumer keys and callback URL. If you don't have a callback URL or publicly accessible UI, consider using [PIN-based authorization](/resources/fundamentals/authentication/oauth-1-0a/pin-based-oauth), which is intended for applications that cannot access or embed a web browser in order to redirect the user after authorization. 

The possible states for the 3-legged sign in interaction are illustrated in the following flowchart:

![](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/obtaining-access-tokens.png.twimg.1920.png)

#### Overview of the process

At a high level, the 3-Legged OAuth process will:

1. Create a request for a consumer application to obtain a request token.
2. Have the user authenticate, and send the consumer application a request token.
3. Convert the request token into a usable user access token.

**Terminology clarification**

In the guide below, you may see different terms referring to the same thing.

**Client credentials:**

* App Key === API Key === Consumer API Key === Consumer Key === Customer Key === `oauth_consumer_key`
* App Key Secret === API Secret Key === Consumer Secret === Consumer Key === Customer Key === `oauth_consumer_secret`
* Callback URL === `oauth_callback`
   

**Temporary credentials:**

* Request Token === `oauth_token`
* Request Token Secret === `oauth_token_secret`
* oauth\_verifier
   

**Token credentials:**

* Access token === Token === resulting `oauth_token`
* Access token secret === Token Secret === resulting `oauth_token_secret`

#### Walkthrough steps

**Step 1: [POST oauth/request\_token](/resources/fundamentals/authentication/api-reference#post-oauth-request-token)**

Create a request for a consumer application to obtain a request token.

The only unique parameter in this request is oauth\_callback, which must be a [URL encoded](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters) version of the URL you wish your user to be redirected to when they complete step 2. The remaining parameters are added by the OAuth signing process.

Please note - any callback URL that you use with the [POST oauth/request\_token](/resources/fundamentals/authentication/api-reference#post-oauth-request-token) endpoint will have to be configured within your [developer App's](/resources/fundamentals/developer-apps) settings in the app details page of Developer Console.
 

**Request includes:**

`oauth_callback="https%3A%2F%2FyourCallbackUrl.com"`

`oauth_consumer_key="cChZNFj6T5R0TigYB9yd1w" `

Your app should examine the HTTP status of the response. Any value other than 200 indicates a failure. The body of the response will contain the `oauth_token`, `oauth_token_secret`, and `oauth_callback_confirmed` parameters. Your app should verify that `oauth_callback_confirmed` is true and store the other two values for the next steps.
 

**Response includes**

`oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0`

`oauth_token_secret=veNRnAWe6inFuo8o2u8SLLZLjolYDmDP7SzL0YfYI`

`oauth_callback_confirmed=true`

**Step 2: [GET oauth/authorize](/resources/fundamentals/authentication/api-reference#get-oauth-authorize)**

Have the user authenticate, and send the consumer application a request token.
 

**Example URL to redirect user to:**

`https://api.x.com/oauth/authorize?oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0`

Upon successful authentication, your `callback_url` would receive a request containing the `oauth_token` and `oauth_verifier` parameters. Your application should verify that the token matches the request token received in step 1.
 

**Request from client’s redirect:**

`https://yourCallbackUrl.com?oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0&oauth_verifier=uw7NjWHT6OJ1MpJOXsHfNxoAhPKpgI8BlYDhxEjIBY`

**Step 3: [POST oauth/access\_token](/resources/fundamentals/authentication/api-reference#post-oauth-access-token)**

Convert the request token into a usable access token.

To render the request token into a usable access token, your application must make a request to the [POST oauth/access\_token](/resources/fundamentals/authentication/api-reference#post-oauth-access-token) endpoint, containing the `oauth_verifier` value obtained in step 2. The request token is also passed in the `oauth_token` portion of the header, but this will have been added by the signing process.
 

**Request includes:**

`POST /oauth/access_token`

`oauth_consumer_key=cChZNFj6T5R0TigYB9yd1w`

`oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0`

`oauth_verifier=uw7NjWHT6OJ1MpJOXsHfNxoAhPKpgI8BlYDhxEjIBY`

A successful response contains the `oauth_token`, `oauth_token_secret` parameters. The token and token secret should be stored and used for future authenticated requests to the X API. To determine the identity of the user, use [GET account/verify\_credentials](/resources/fundamentals/authentication/api-reference).
 

**Response includes:**

`oauth_token=7588892-kagSNqWge8gB1WwE3plnFsJHAZVfxWD7Vb57p0b4`

`oauth_token_secret=PbKfYqSryyeKDWz4ebtY3o5ogNLG11WJuZBc9fQrQo`

**Using these credentials for OAuth 1.0a (application-user) required requests**

Now you've obtained the user access tokens; you can use them to access certain APIs such as [POST statuses/update](/x-api/posts/manage-tweets/introduction) to create Tweets on the users' behalf.
 

**Request includes:**

`POST statuses/update.json`

`oauth_consumer_key=cChZNFj6T5R0TigYB9yd1w`

`oauth_token=7588892-kagSNqWge8gB1WwE3plnFsJHAZVfxWD7Vb57p0b4`

#### Sample use case

The standard flow is web-based and uses the 3-legged authorization OAuth flow. The screenshots outlined here are part of a sample that you can view the source of at [https://github.com/xdevplatform/twauth-web](https://github.com/xdevplatform/twauth-web).

At some point in your application, you will want to redirect to X in order to authorize your application.

<Frame>
  <img alt="" />
</Frame>

When you redirect to X with the request token, the user will be prompted to authorize your application.

<Frame>
  <img alt="" />
</Frame>

Upon authorizing your application, the user will be redirected to the callback URL provided when you generated the request token. You will use this to obtain the permanent access token for this user and store it locally.

<Frame>
  <img alt="" />
</Frame>


# OAuth 1.0a
Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/overview

Overview of OAuth 1.0a user context authentication on X, covering API keys, access tokens, request signing, and tools for making authorized API calls.

## OAuth 1.0a

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. For example, if you have a X developer app, you can make API requests on behalf of any X account as long as that user authenticates your app.

Please note: if you aren’t familiar with concepts such as HMAC-SHA1 and percent encoding, we recommend that you check out the "useful tools" section below that lists some API clients that greatly simplify the authentication process.

### Key concepts

#### Signing a request with keys and tokens

You have to sign each API request by passing several generated keys and tokens in an authorization header. To start, you can generate several keys and tokens in your [X developer app’s](/resources/fundamentals/developer-apps) details page, including the following:

|                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API key and secret:<br /><br />`oauth_consumer_key`<br /><br />`oauth_consumer_secret` | Think of these as the user name and password that represents your X developer app when making API requests.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Access token and secret:<br /><br />`oauth_token`<br /><br />`oauth_token_secret`      | An access token and access token secret are user-specific credentials used to authenticate OAuth 1.0a API requests. They specify the X account the request is made on behalf of.<br /><br />You can generate your own access token and token secret if you would like your app to make requests on behalf of the same X account associated with your developer account on the [X developer app's](/resources/fundamentals/developer-apps) details page.<br /><br />If you'd like to generate access tokens for a different user, see "Making requests on behalf of users" below. |

#### Making requests on behalf of users

When creating a signature, you need a set of access tokens that represent the user that you are going to make a request on behalf of.

You can generate a set of access tokens that represents the X account that owns the X developer app from the [app’s details page,](https://developer.x.com/content/developer-twitter/en/apps) but if you are wanting to make a request on behalf of a different X account, that account’s owner must grant access to you by signing in to their account as part of the [3-legged OAuth flow](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow). The output of this process is a set of access tokens (oauth\_token and oauth\_token\_secret) that can be used to make an OAuth 1.0a request.

Once you have these keys and tokens, you can either [create a signature](/resources/fundamentals/authentication#creating-a-signature) from scratch. We don't recommend this unless you know what you are doing, or if you're using one of the tools mentioned below to make a request to an endpoint that requires OAuth 1.0a.

For reference, here is an example of a signed cURL request with all of the generated tokens passed in an authorization header:

```bash theme={null}
curl --request POST \
  --url 'https://api.x.com/1.1/statuses/update.json?status=Hello%20world' \
  --header 'authorization: OAuth oauth_consumer_key="CONSUMER_API_KEY", oauth_nonce="OAUTH_NONCE", oauth_signature="OAUTH_SIGNATURE", oauth_signature_method="HMAC-SHA1", oauth_timestamp="OAUTH_TIMESTAMP", oauth_token="ACCESS_TOKEN", oauth_version="1.0"' \
```

<Note>
  **Note:** User access tokens are sensitive and should be guarded very carefully. When access tokens are generated, the user they represent is trusting your application to keep them secure. If the security of both API keys and user access tokens are compromised, your application would potentially expose access to private information and account functionality. We encourage you to learn more about [securing keys and access tokens](/resources/fundamentals/developer-apps).
</Note>

### Useful tools

The process of [signing a request](/resources/fundamentals/authentication#creating-a-signature) is complicated. We recommend that you use an API client library that automatically generates a lot of the authentication token:

|                                        |                                                                                                                                                                                     |
| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Postman](https://www.getpostman.com/) | An API client that lets you build and send REST API requests. Read our “[Getting started with Postman](/tutorials/postman-getting-started)” tutorial to learn more about this tool. |
| [Insomnia](https://insomnia.rest/)     | Insomnia is a REST API Client with cookie management, environment variables, code generation, and authentication for Mac, Window, and Linux.                                        |


# Percent encoding parameters
Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters

Apply RFC 3986 percent encoding to OAuth 1.0a parameters for X API requests, with rules for reserved characters and worked URL encoding examples.

### Percent encoding parameters

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.ietf.org/html/rfc3986#section-2.1). Since many implementations of URL encoding algorithms are not fully compatible with RFC 3986, bad encodings are a cause of many OAuth signature errors. For this reason, the exact signing algorithm to use is covered on this page.

This page covers the URL encoding process described in [RFC 3986, Section 2.1](http://tools.ietf.org/html/rfc3986#section-2.1). We encourage you to reference that specification in case of any ambiguity or conflict with this document.
 

#### Encoding a string

The following algorithm assumes you are encoding a string SRC by copying its values byte-by-byte to a string DST.

**Step 1: While SRC contains unread bytes, read the next byte (8 bits) from SRC.** Typically, this is considered a character, but in the case of encodings where a character may be more than one byte (such as UTF-8), just read the first byte.

**Step 2: Check whether the read byte matches any of the following ASCII equivalents.** The following table has been broken down into rows for legibility, but you only need to determine whether the read byte exists in the table at all, not the specific row.

| Name                | ASCII characters                                                                                                                 | Equivalent byte values                                                                                                                                 |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Digits              | ‘0’, ‘1’, ‘2’, ‘3’, ‘4’, ‘5’, ‘6’, ‘7’, ‘8’, ‘9’                                                                                 | 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39                                                                                             |
| Uppercase letters   | ‘A’, ‘B’, ‘C’, ‘D’, ‘E’, ‘F’, ‘G’, ‘H’, ‘I’, ‘J’, ‘K’, ‘L’, ‘M’, ‘N’, ‘O’, ‘P’, ‘Q’, ‘R’, ‘S’, ‘T’, ‘U’, ‘V’, ‘W’, ‘X’, ‘Y’, ‘Z’ | 0x41, 0x42, 0x43, 0x44, 0x45,0x46, 0x47, 0x48, 0x49, 0x4A, 0x4B,0x4C, 0x4D, 0x4E, 0x4F, 0x50, 0x51,0x52, 0x53, 0x54, 0x55, 0x56, 0x57,0x58, 0x59, 0x5A |
| Lowercase letters   | ‘a’, ‘b’, ‘c’, ‘d’, ‘e’, ‘f’, ‘g’, ‘h’, ‘i’, ‘j’, ‘k’, ‘l’, ‘m’, ‘n’, ‘o’, ‘p’, ‘q’, ‘r’, ‘s’, ‘t’, ‘u’, ‘v’, ‘w’, ‘x’, ‘y’, ‘z’ | 0x61, 0x62, 0x63, 0x64, 0x65,0x66, 0x67, 0x68, 0x69, 0x6A, 0x6B,0x6C, 0x6D, 0x6E, 0x6F, 0x70, 0x71,0x72, 0x73, 0x74, 0x75, 0x76, 0x77,0x78, 0x79, 0x7A |
| Reserved characters | ‘-‘, ‘.’, ‘\_’, ‘\~’                                                                                                             | 0x2D, 0x2E, 0x5F, 0x7E                                                                                                                                 |

**Step 2b: If the byte is not listed in the above table, continue.** Any other value must be encoded. **Step 2a: If the byte is listed in the above table, copy it into DST and go back to Step 1.** Characters listed in the above table do not need to be escaped, so you will just copy the byte directly.

**Step 3: Write the character ‘%’ to DST.** The percent character ‘%’ (or 0x25 in hex and 00100101 in binary) indicates that the next two bytes will represent an encoded byte.

**Step 4: Write two characters representing the uppercase ASCII-encoded hex value of the current byte to DST.** This is a bit confusing, so here is an example. Pretend the current byte is 0xE6 (11100110 in binary). This corresponds with the UTF-8 encoded value of ‘æ’. To encode this value, write the character ‘E’ (0x45, from the table above) and then the character ‘6’ (0x36) to DST. The last three characters are written should have been “%E6”. Note that if you write a letter such as A,B,C,D,E or F, you must use the uppercase character.

**Step 5: Return to Step 1.** Keep going until the entirety of SRC is copied to DST.
 

#### Examples

The following examples may be helpful to compare with the output of your own code. You should consider any differences an error. Spaces encoded as “+” characters are an example of incorrect encoding.

| Original string    | Encoded string              |
| :----------------- | :-------------------------- |
| Ladies + Gentlemen | Ladies%20%2B%20Gentlemen    |
| An encoded string! | An%20encoded%20string%21    |
| Dogs, Cats & Mice  | Dogs%2C%20Cats%20%26%20Mice |
| ☃                  | %E2%98%83                   |


# PIN-based authorization
Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/pin-based-oauth

Use the PIN-based OAuth flow for X apps that cannot embed a browser, like CLI tools and game consoles, by entering a numeric PIN as the oauth_verifier.

### PIN-based authorization

The PIN-based OAuth flow is a version of the [3-legged OAuth](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) process and is intended for applications that cannot access or embed a web browser to redirect the user after authorization. Examples of such applications would be command-line applications, embedded systems, game consoles, and certain types of mobile apps.

PIN-based OAuth flow is initiated by an app in the `request_token` with the `oauth_callback` set to `oob`. The term `oob` means out-of-band OAuth.  The user still visits X to login or authorize the app, but they will not be automatically redirected to the application upon approving access. Instead, they will see a numerical PIN code, with instructions to return to the application and enter this value.

<Note>
  **Note:** The `callback_url` within the X app settings is still required, even when using PIN-based auth.
</Note>

 

#### Implementing the PIN-based OAuth flow

The PIN-based flow is implemented in the same way as [3-legged authorization](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) (and [Sign in with X](/resources/fundamentals/authentication#log-in-with-x)), with the following differences:

1. The value for `oauth_callback` must be set to `oob` during the [POST oauth/request\_token](/resources/fundamentals/authentication/api-reference#post-oauth-request-token) call.

2. After the user is sent to X to authorize your app using either a [GET oauth/authenticate](/resources/fundamentals/authentication/api-reference#get-oauth-authenticate) or [GET oauth/authorize URL](/resources/fundamentals/authentication/api-reference#get-oauth-authorize), they will not be redirected to your `callback_url`, instead they will see a screen with a X generated \~7 digit PIN with directions to enter the PIN into your applications name.

3. The user enters this PIN into your application, and your application uses the PIN number as the `oauth_verifier` in the [POST oauth/access\_token](/resources/fundamentals/authentication/api-reference#post-oauth-access-token) to obtain an access\_token.

<Note>
  **Note:** PIN numbers are not reusable, and the `access_token` obtained should be used for application-user requests.
</Note>


# App only authentication and OAuth 2.0 Bearer Token
Source: https://docs.x.com/fundamentals/authentication/oauth-2-0/application-only

Authenticate X API requests with OAuth 2.0 App-Only Bearer Tokens for server-to-server, read-only access to public data without a user context.

### App only authentication and OAuth 2.0 Bearer Token

X offers applications the ability to issue authenticated requests on behalf of the application itself, as opposed to on behalf of a specific user. X's implementation is based on the [Client Credentials Grant](http://tools.ietf.org/html/rfc6749#section-4.4) flow of the [OAuth 2 specification](http://tools.ietf.org/html/rfc6749).

Application-only authentication doesn't include any user-context and is a form of authentication where an application makes API requests on its own behalf. This method is for developers that just need read-only access to public information. 

You can do application-only authentication using your apps consumer API keys, or by using an App only Access Token (Bearer Token). This means that the only requests you can make to a X API must not require an authenticated user.

With application-only authentication, you can perform actions such as:

* Pull user timelines
* Access friends and followers of any account
* Access lists resources
* Search Tweets

Please note that only [OAuth 1.0a](/resources/fundamentals/authentication/oauth-1-0a/api-key-and-secret) or [OAuth 2.0 Authorization Code Flow](/resources/fundamentals/authentication/oauth-2-0/authorization-code) with PKCE is required to issue requests on behalf of users. The [API reference](/resources/fundamentals/authentication/api-reference) page describes the authentication method required to use an API. You will need user-authentication, user-context, with an [access token](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) to perform the following:

* Post Tweets or other resources
* Search for users
* Use any geo endpoint
* Access Direct Messages or account credentials
* Retrieve user's email addresses

#### Auth Flow

To use this method, you need to use a [App only Access Token](/resources/fundamentals/authentication/oauth-2-0/application-only)(also known as [Bearer Token](/resources/fundamentals/authentication/oauth-2-0/bearer-tokens)). You can generate an App only Access Token (Bearer Token) by passing your consumer key and secret through the [POST oauth2/token](/resources/fundamentals/authentication/api-reference#post-oauth2-token) endpoint. 

The application-only auth flow follows these steps:

* An application encodes its consumer key and secret into a specially encoded set of credentials.
* An application makes a request to the [POST oauth2/token](/resources/fundamentals/authentication/api-reference#post-oauth2-token) endpoint to exchange these credentials for an [App only Access Token](/resources/fundamentals/authentication/oauth-2-0/application-only).
* When accessing the REST API, the application uses the App only Access Token to authenticate.

Because there is no need to sign a request, this approach is much simpler than the standard OAuth 1.0a model.

<Frame>
  <img alt="" />
</Frame>

#### About application-only auth

**Tokens are passwords**

Keep in mind that the consumer key & secret and the App only Access Token (Bearer Token) itself grant access to make requests on behalf of an application. These values should be considered as sensitive as passwords, and must not be shared or distributed to untrusted parties.

**SSL required**

All requests (both to obtain and use the tokens) *must* use HTTPS endpoints. Follow the best practices detailed in [Connecting to X API using TLS](/resources/fundamentals/authentication/guides/tls) — peers should **always** be verified.

**No user-context**

When issuing requests using application-only auth, there is no concept of a "current user". Therefore, endpoints such as [POST statuses/update](/x-api/posts/creation-of-a-post) will not function with application-only auth. See [using OAuth](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) for more information for issuing requests on behalf of a user.

**Rate limiting**

Applications have two kinds of rate limiting pools.

Requests made on behalf of users with access tokens, also known as user-context, depletes from a different rate limiting context than that used in application-only authentication. So, in other words, requests made on behalf of users will not deplete from the rate limits available through app-only auth, and requests made through app-only auth will not deplete from the rate limits used in user-based auth.

Read more about [API Rate Limiting](/x-api/fundamentals/rate-limits) and [review the limits](https://developer.x.com/en/portal/products).

#### Issuing application-only requests

**Step 1: Encode consumer key and secret**

The steps to encode an application’s consumer key and secret into a set of credentials to obtain a Bearer Token are:

1. URL encode the consumer key and consumer secret according to [RFC 1738](http://www.ietf.org/rfc/rfc1738.txt). Note that at the time of writing, this will not actually change the consumer key and secret, but this step should still be performed in case the format of those values changes in the future.
2. Concatenate the encoded consumer key, a colon character ":", and the encoded consumer secret into a single string.
3. [Base64 encode](http://en.wikipedia.org/wiki/Base64) the string from the previous step.

Below are example values showing the result of this algorithm. Note that the consumer secret used in this page is for test purposes and will not work for real requests.

|                                                               |                                                                                             |
| :------------------------------------------------------------ | :------------------------------------------------------------------------------------------ |
| Consumer key                                                  | xvz1evFS4wEEPTGEFPHBog                                                                      |
| Consumer secret                                               | L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg                                                   |
| RFC 1738 encoded consumer<br /><br />key (does not change)    | xvz1evFS4wEEPTGEFPHBog                                                                      |
| RFC 1738 encoded consumer<br /><br />secret (does not change) | L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg                                                   |
| Bearer Token credentials                                      | xvz1evFS4wEEPTGEFPHBog:L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg                            |
| Base64 encoded Bearer Token credentials                       | :: eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJnNmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw== |

**Step 2: Obtain an App only Access Token (Bearer Token)**

The value calculated in step 1 must be exchanged for an App only Access Token by issuing a request to [POST oauth2/token](/resources/fundamentals/authentication/api-reference#post-oauth2-token):

* The request must be an HTTP POST request.
* The request must include an `Authorization` header with the value of `Basic <base64 encoded value from step 1>.`
* The request must include a `Content-Type` header with the value of `application/x-www-form-urlencoded;charset=UTF-8.`
* The body of the request must be `grant_type=client_credentials`.

**Example request (Authorization header has been wrapped):**

```json theme={null}
POST /oauth2/token HTTP/1.1
Host: api.x.com
User-Agent: My X App v1.0.23
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29
Accept-Encoding: gzip

grant\_type=client\_credentials
```

If the request was formatted correctly, the server would respond with a JSON-encoded payload:

**Example response:**

```json theme={null}
HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
...
Content-Encoding: gzip
Content-Length: 140

{"token\_type":"bearer","access\_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}
```

Applications should verify that the value associated with the `token_type` key of the returned object is `bearer`. The value associated with the `access_token` key is the App only Access Token (Bearer Token).

Note that one App only Access Token is valid for an application at a time. Issuing another request with the same credentials to `/oauth2/token` will return the same token until it is invalidated.

**Step 3: Authenticate API requests with the App only Access Token (Bearer Token)**

The App only Access Token (Bearer Token) may be used to issue requests to API endpoints that support application-only auth. To use the App Access Token, construct a normal HTTPS request and include an `Authorization` header with the value of `Bearer <base64 bearer token value from step 2>. Signing is not required.`

**Example request (Authorization header has been wrapped):**

```
GET /1.1/statuses/user\_timeline.json?count=100&screen\_name=twitterapi HTTP/1.1
Host: api.x.com
User-Agent: My X App v1.0.23
Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAA
                      AAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Accept-Encoding: gzip
```

**Invalidating an App only Access Token (Bearer Token)**

Should an App only Access Token become compromised or need to be invalidated for any reason, issue a call to [POST oauth2/invalidate\_token](/resources/fundamentals/authentication/api-reference#post-oauth2-invalidate-token).

**Example request (Authorization header has been wrapped):**

```bash theme={null}
POST /oauth2/invalidate_token HTTP/1.1
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
User-Agent: My X App v1.0.23
Host: api.x.com
Accept: */*
Content-Length: 119
Content-Type: application/x-www-form-urlencoded

access_token=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
```

**Example response:**

```json theme={null}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 127
...

{"access_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}
```

#### Common error cases

This section describes some common mistakes involved in the negotiation and use of Bearer Tokens. Be aware that not all possible error responses are covered here - be observant of unhandled error codes and responses.

**Invalid requests to obtain or revoke an App only Access Token**

Attempts to:

* Obtain an App only Access Token (Bearer Token) with an invalid request (for example, leaving out `grant_type=client_credentials`).
* Obtain or revoke an App only Access Token (Bearer Token) with incorrect or expired app credentials.
* Invalidate an incorrect or revoked App only Access Token (Bearer Token).
* Obtain an App only Access Token (Bearer Token) too frequently in a short period of time.

Will result in:

```json theme={null}
HTTP/1.1 403 Forbidden
Content-Length: 105
Content-Type: application/json; charset=utf-8
...

{"errors":\[{"code":99,"label":"authenticity\_token\_error","message":"Unable to verify your credentials"}\]}
```

#### API request contains invalid App only Access Token (Bearer Token)

Using an incorrect or revoked Access Token to make API requests will result in:

```json theme={null}
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 61
...

{"errors":\[{"message":"Invalid or expired token","code":89}\]}
```

#### App only Access Token (Bearer Token) used on endpoint which doesn't support application-only auth

Requesting an endpoint which requires a user context (such as `statuses/home_timeline`) with an App only Access Token (Bearer Token) will produce:

```json theme={null}
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 91
...

{"errors":\[{"message":"Your credentials do not allow access to this resource","code":220}\]}
```


# OAuth 2.0 Authorization Code Flow with PKCE
Source: https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code

Reference for the X OAuth 2.0 Authorization Code Flow with PKCE, covering scopes, refresh tokens, confidential clients, and access token lifetimes.

### OAuth 2.0 Authorization Code Flow with PKCE

#### Introduction

OAuth 2.0 is an industry-standard authorization protocol that 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 App’s authentication settings found in the App settings section of the Developer Console.

#### How long will my credentials stay valid?  

By default, the access token you create through the Authorization Code Flow with PKCE will only stay valid for two hours unless you’ve used the `offline.access` scope.

#### Refresh tokens

Refresh tokens allow an application to obtain a new access token without prompting the user via the refresh token flow.

If the scope `offline.access` is applied an OAuth 2.0 refresh token will be issued. With this refresh token, you obtain an access token. If this scope is not passed, we will not generate a refresh token.

An example of the request you would make to use a refresh token to obtain a new access token is as follows:

```bash theme={null}
POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token=bWRWa3gzdnk3WHRGU1o0bmRRcTJ5VUxWX1lZTDdJSUtmaWcxbTVxdEFXcW5tOjE2MjIxNDc3NDM5MTQ6MToxOnJ0OjE' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ
```

#### App settings

You can select your App’s authentication settings to be OAuth 1.0a or OAuth 2.0. You can also enable an App to access both OAuth 1.0a and OAuth 2.0.

OAuth 2.0 can be used with the X API v2 only. If you have selected OAuth 2.0 you will be able to see a Client ID in your App’s Keys and Tokens section. 

#### Confidential clients

[Confidential clients](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1) can hold credentials in a secure way without exposing them to unauthorized parties and securely authenticate with the authorization server they keep your client secret safe. Public clients as they’re usually running in a browser or on a mobile device and are unable to use your client secrets. If you select a type of App that is a confidential client, you will be provided with a client secret. 

If you selected a type of client that is a confidential client in the Developer Console, you will also be able to see a Client Secret. Your options are Native App, Single page App, Web App, Automated App, or bot. Native App and Single page Apps are public clients and Web App and Automated App or bots are confidential clients.

You don’t need client id for confidential clients with a valid Authorization Header. You still are required to include Client Id in the body for the requests with a public client. 

#### Scopes

Scopes allow you to set granular access for your App so that your App only has the permissions that it needs. To learn more about what scopes map to what endpoints, view our [authentication mapping guide](/resources/fundamentals/authentication/guides/v2-authentication-mapping).

|                      |                                                                                                              |
| :------------------- | :----------------------------------------------------------------------------------------------------------- |
| **Scope**            | **Description**                                                                                              |
| tweet.read           | All the Tweets you can view, including Tweets from protected accounts.                                       |
| tweet.write          | Tweet and Retweet for you.                                                                                   |
| tweet.moderate.write | Hide and unhide replies to your Tweets.                                                                      |
| users.email          | Email from an authenticated user.                                                                            |
| users.read           | Any account you can view, including protected accounts.                                                      |
| follows.read         | People who follow you and people who you follow.                                                             |
| follows.write        | Follow and unfollow people for you.                                                                          |
| offline.access       | Stay connected to your account until you revoke access.                                                      |
| space.read           | All the Spaces you can view.                                                                                 |
| mute.read            | Accounts you’ve muted.                                                                                       |
| mute.write           | Mute and unmute accounts for you.                                                                            |
| like.read            | Tweets you’ve liked and likes you can view.                                                                  |
| like.write           | Like and un-like Tweets for you.                                                                             |
| list.read            | Lists, list members, and list followers of lists you’ve created or are a member of, including private lists. |
| list.write           | Create and manage Lists for you.                                                                             |
| block.read           | Accounts you’ve blocked.                                                                                     |
| block.write          | Block and unblock accounts for you.                                                                          |
| bookmark.read        | Get Bookmarked Tweets from an authenticated user.                                                            |
| bookmark.write       | Bookmark and remove Bookmarks from Tweets.                                                                   |
| dm.read              | All the Direct Messages you can view, including Direct Messages from protected accounts.                     |
| dm.write             | Send and manage Direct Messages for you.                                                                     |
| media.write          | Upload media.                                                                                                |

#### Rate limits

For the most part, the rate limits are the same as they are authenticating with OAuth 1.0a, with the exception of Tweets lookup and Users lookup. We are increasing the per-App limit from 300 to 900 requests per 15 minutes while using OAuth 2.0 for Tweet lookup and user lookup. To learn more be sure to check out our [documentation on rate limits](/resources/fundamentals/rate-limits).

#### Grant types

We only provide [authorization code](https://oauth.net/2/grant-types/authorization-code/) with [PKCE](https://oauth.net/2/pkce/) and [refresh token](https://oauth.net/2/grant-types/refresh-token/) as the supported [grant types](https://oauth.net/2/grant-types/) for this initial launch. We may provide more grant types in the future.

#### OAuth 2.0 flow

OAuth 2.0 uses a similar flow to what we are currently using for OAuth 1.0a. You can check out a diagram and detailed explanation in our [documentation on this subject](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens). 

#### Glossary

|                         |                                                                                                                                                                                                                                                                                                         |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Term**                | **Description**                                                                                                                                                                                                                                                                                         |
| Grant types             | The OAuth framework specifies several grant types for different use cases and a framework for creating new grant types. Examples include authorization code, client credentials, device code, and refresh token.                                                                                        |
| Confidential client     | Clients are applications that can securely authenticate with the authorization server, for example, keeping their registered client secret safe.                                                                                                                                                        |
| Public client           | Clients cannot use registered client secrets, such as applications running in a browser or mobile device.                                                                                                                                                                                               |
| Authorization code flow | Used by both confidential and public clients to exchange an authorization code for an access token.                                                                                                                                                                                                     |
| PKCE                    | An extension to the authorization code flow to prevent several attacks and to be able to perform the OAuth exchange from public clients securely.                                                                                                                                                       |
| Client ID               | Can be found in the keys and tokens section of the Developer Console under the header "Client ID." If you don't see this, please get in touch with our team directly. The Client ID will be needed to generate the authorize URL.                                                                       |
| Redirect URI            | Your callback URL. You will need to have [exact match validation](https://datatracker.ietf.org/doc/html/rfc6749#section-10.6).                                                                                                                                                                          |
| Authorization code      | This allows an application to hit APIs on behalf of users. Known as the auth\_code. The auth\_code has a time limit of 30 seconds once the App owner receives an approved auth\_code from the user. You will have to exchange it with an access token within 30 seconds, or the auth\_code will expire. |
| Access token            | Access tokens are the token that applications use to make API requests on behalf of a user.                                                                                                                                                                                                             |
| Refresh token           | Allows an application to obtain a new access token without prompting the user via the refresh token flow.                                                                                                                                                                                               |
| Client Secret           | If you have selected an App type that is a confidential client you will be provided with a “Client Secret” under “Client ID” in your App’s keys and tokens section.                                                                                                                                     |

#### Parameters

To construct an OAuth 2.0 authorize URL, you will need to ensure you have the following parameters in the authorization URL. 

|                         |                                                                                                                                                                                                                                                            |
| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Parameter**           | **Description**                                                                                                                                                                                                                                            |
| response\_type          | You will need to specify that this is a code with the word “code”.                                                                                                                                                                                         |
| client\_id              | Can be found in the Developer Console under the header "Client ID".                                                                                                                                                                                        |
| redirect\_uri           | Your callback URL. This value must correspond to one of the Callback URLs defined in your App’s settings. For OAuth 2.0, you will need to have [exact match validation](https://datatracker.ietf.org/doc/html/rfc6749#section-10.6) for your callback URL. |
| state                   | A random string you provide to verify against [CSRF attacks](https://auth0.com/docs/protocols/state-parameters).  The length of this string can be up to 500 characters.                                                                                   |
| code\_challenge         | A [PKCE](https://www.oauth.com/oauth2-servers/pkce/authorization-request/) parameter, a random secret for each request you make.                                                                                                                           |
| code\_challenge\_method | Specifies the method you are using to make a request (S256 OR plain).                                                                                                                                                                                      |

#### Authorize URL 

With OAuth 2.0, you create an authorize URL, which you can use to allow a user to authenticate via an authentication flow, similar to “Sign In” with X. 

An example of the URL you are creating is as follows: 

```
https://x.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https://www.example.com&scope=tweet.read%20users.read%20account.follows.read%20account.follows.write&state=state&code_challenge=challenge&code_challenge_method=plain
```

You will need to have the proper encoding for this URL to work, be sure to check out our documentation on the [percent encoding](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters).


# Using and generating an app-only Bearer Token
Source: https://docs.x.com/fundamentals/authentication/oauth-2-0/bearer-tokens

Generate and use an app-only Bearer Token for X API OAuth 2.0 application-only authentication with a curl request to the oauth2/token endpoint.

### Using and generating an app-only Bearer Token

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.0. 

Authentication, which uses a Bearer Token, is also known as application-only authentication. A Bearer Token is a byte array of unspecified format that you generate using a script like a curl command. You can also obtain a Bearer Token from the Developer Console inside the keys and tokens section of your App's settings. More information about this feature can be found on [OAuth's official documentation](https://oauth.net/2/bearer-tokens/).

#### When are they used?

The products that require the use of a Bearer Token are as follows:

* [Engagement API](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api)
* [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity)
* Other APIs that utilize OAuth 2.0 Bearer Token authentication such as v2 and Labs endpoints.

#### Prerequisites

You will need to [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info) and to have created a [X App](/resources/fundamentals/developer-apps). Once you have those, you'll also need to obtain the API keys found in the [Developer Console](/resources/fundamentals/developer-portal). Follow the steps below:

1. Login to your X account on developer.x.com.
2. Navigate to the [X App dashboard](https://developer.x.com/content/developer-twitter/en/apps) and open the X App for which you would like to generate access tokens.
3. Navigate to the "keys and tokens" page.
4. You'll find the API keys, user Access Tokens, and Bearer Token on this page.

### How to generate a Bearer Token

You can find the Bearer Token for your App with the rest of your "Keys and Tokens".

Copy the following cURL request into your command line after making changes to the following consumer API keys previously obtained from your [X App](/resources/fundamentals/developer-apps). Note that the consumer API keys used on this page have been decommissioned and will not work for real requests.

* **API key** `<API key>` e.g.`xvz1evFS4wEEPTGEFPHBog`
* **API secret key** `<API secret key>` e.g. `L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg`

  ```bash theme={null}
  curl -u "$API_KEY:$API_SECRET_KEY" \
  --data 'grant_type=client_credentials' \
  'https://api.x.com/oauth2/token'
  ```

Here's an example of how the curl request should look with your API keys entered:

```bash theme={null}
curl -u 'xvz1evFS4wEEPTGEFPHBog:L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg' \
--data 'grant_type=client_credentials' \
'https://api.x.com/oauth2/token'
```

Here is what the response would look like. Note that this is a decommissioned Bearer Token:

`{"token_type":"bearer","access_token":"AAAAAAAAAAAAAAAAAAAAAMLheAAAAAAA0%2BuSeid%2BULvsea4JtiGRiSDSJSI%3DEUifiRBkKG5E2XzMDjRfl76ZC9Ub0wnz4XsNiRVBChTYbJcE3F"}`

Our Bearer Token used to authenticate to resources with OAuth 2.0 would be:

`AAAAAAAAAAAAAAAAAAAAAMLheAAAAAAA0%2BuSeid%2BULvsea4JtiGRiSDSJSI%3DEUifiRBkKG5E2XzMDjRfl76ZC9Ub0wnz4XsNiRVBChTYbJcE3F`


# OAuth 2.0
Source: https://docs.x.com/fundamentals/authentication/oauth-2-0/overview

OAuth 2.0 Bearer Token authenticates requests on behalf of your developer App. As this method is specific to the App, it does not involve any users.

### Bearer Token (also known as app-only)

OAuth 2.0 Bearer Token authenticates requests on behalf of your [developer App](/resources/fundamentals/developer-apps). As this method is specific to the App, it does not involve any users. This method is typically for developers that need read-only access to public information. 

This authentication method requires for you to pass a Bearer Token with your request, which you can generate within the Keys and tokens section of your developer Apps. Here is an example of what a request looks like with a fake Bearer Token:

```json theme={null}
curl "https://api.x.com/2/tweets?ids=1261326399320715264,1278347468690915330" \
-H "Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAFnz2wAAAAAAxTmQbp%2BIHDtAhTBbyNJon%2BA72K4%3DeIaigY0QBrv6Rp8KZQQLOTpo9ubw5Jt?WRE8avbi"
```

API calls using app-only authentication are [rate limited](/resources/fundamentals/rate-limits) per endpoint at the App level.

To use this method, you'll need a Bearer Token, which you can generate by passing your API Key and Secret through the [POST oauth2/token](/resources/fundamentals/authentication/api-reference#post-oauth2-token) endpoint, or by generating it in the "keys and token" section of your App settings in the [Developer Console](/resources/fundamentals/developer-portal).

If you'd like to revoke a Bearer Token, you can use the [POST oauth2/invalidate\_token](/resources/fundamentals/authentication/api-reference#post-oauth2-invalidate-token) endpoint, or click where it says "revoke" next to the Bearer Token in the "keys and tokens" section of your App settings.

### OAuth 2.0 Authorization Code Flow with PKCE

OAuth 2.0 Authorization Code Flow with PKCE allows you to authenticate on behalf of another user with more control over an application’s scopes and improves authorization flows across multiple devices. In other words, developers building applications for people on X will have more control over the information their App requests from its users, so that you only have to ask your end-users for the data and information you need.

This modern authorization protocol will allow you to present your end-users with a more streamlined consent flow for authorizing your app, which only displays the specific scopes you have requested from them. Not only does this reduce your data burden, but it may also lead to increased trust from end-users.


# OAuth 2.0 Authorization Code Flow with PKCE
Source: https://docs.x.com/fundamentals/authentication/oauth-2-0/user-access-token

Step-by-step guide to connecting users to X API v2 endpoints with OAuth 2.0 Authorization Code Flow with PKCE, including authorize URLs and token exchange.

### How to connect to endpoints using OAuth 2.0 Authorization Code Flow with PKCE

#### How to connect to the endpoints

To authenticate your users, your App will need to implement an authorization flow. This authorization flow lets you direct your users to an authorization dialog on X. From there, the primary X experience will show the authorization dialog and handle the authorization on behalf of your App. Your users will be able to authorize your App or decline permission. After the user makes their choice, X will redirect the user to your App, where you can exchange the authorization code for an access token (if the user authorized your App), or handle a rejection (if the user did not authorize your App).

#### Working with confidential clients

If you are working with confidential clients, you will need to use a [basic authentication](https://datatracker.ietf.org/doc/html/rfc2617#section-2) scheme for generating an authorization header with base64 encoding while making requests to the token endpoints.

The `userid` and `password` are separated by a single colon (":") character within a base64 encoded string in the credentials.

An example would look like this:

`-header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='`

If the user agent wishes to send the Client ID "Aladdin" and password "open sesame,” it would use the following header field:

`Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==`

To create the basic authorization header you will need to base64 encoding on your Client ID and Client Secret which can be obtained from your App’s “Keys and Tokens” page inside of the [Developer Console.](https://developer.x.com/en/portal/dashboard)

#### Steps to connect using OAuth 2.0

**Step 1: Construct an Authorize URL**

Your App will need to build an authorize URL to X, indicating the scopes your App needs to authorize. For example, if your App needs to lookup Tweets, users and to manage follows, it should request the following scopes:

`tweet.read%20users.read%20follows.read%20follows.write`

The URL will also contain the `code_challenge` and state parameters, in addition to the other required parameters. In production you should use a random string for the `code_challenge`.

**Step 2: GET oauth2/authorize**

Have the user authenticate and send the application an authorization code. If you have enabled OAuth 2.0 for your App you can find your Client ID inside your App’s “Keys and Tokens” page.

An example URL to redirect the user to would look like this:

```
https://x.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https://www.example.com&scope=tweet.read%20users.read%20follows.read%20follows.write&state=state&code_challenge=challenge&code_challenge_method=plain
```

An example URL with offline\_access would look like this:

```
https://x.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https://www.example.com&scope=tweet.read%20users.read%20follows.read%20offline.access&state=state&code_challenge=challenge&code_challenge_method=plain
```

Upon successful authentication, the redirect\_uri  you would receive a request containing the auth\_code parameter. Your application should verify the state parameter.

An example request from client’s redirect would be:

```
https://www.example.com/?state=state&code=VGNibzFWSWREZm01bjN1N3dicWlNUG1oa2xRRVNNdmVHelJGY2hPWGxNd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE
```

**Step 3: POST oauth2/token - Access Token**

At this point, you can use the authorization code to create an access token and refresh token (only if `offline.access` scope is requested). You can make a POST request to the following endpoint:

```
https://api.x.com/2/oauth2/token
```

You will need to pass in the `Content-Type` of `application/x-www-form-urlencoded` via a header.  Additionally, you should have in your request: `code`, `grant_type`, `client_id` and `redirect_uri`, and the `code_verifier`.

Here is an example token request for a public client:

```json theme={null}
curl --location --request POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=VGNibzFWSWREZm01bjN1N3dicWlNUG1oa2xRRVNNdmVHelJGY2hPWGxNd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ' \
--data-urlencode 'redirect_uri=https://www.example.com' \
--data-urlencode 'code_verifier=challenge'
```

Here is an example using a confidential client: 

```json theme={null}
curl --location --request POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='\
--data-urlencode 'code=VGNibzFWSWREZm01bjN1N3dicWlNUG1oa2xRRVNNdmVHelJGY2hPWGxNd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=https://www.example.com' \
--data-urlencode 'code_verifier=challenge'
```

**Step 4: Connect to the APIs**

You are now ready to connect to the endpoints using OAuth 2.0. To do so, you will request the API as you would using [Bearer Token authentication](/resources/fundamentals/authentication/oauth-2-0/application-only). Instead of passing your Bearer Token, you’ll want to use the access token you generated in the last step. As a response, you should see the appropriate payload corresponding to the endpoint you are requesting. This request is the same for both public and confidential clients. 

An example of the request you would make would look as follows:

```json theme={null}
curl --location --request GET 'https://api.x.com/2/tweets?ids=1261326399320715264,1278347468690915330' \
--header 'Authorization: Bearer Q0Mzb0VhZ0V5dmNXSTEyNER2MFNfVW50RzdXdTN6STFxQlVkTGhTc1lCdlBiOjE2MjIxNDc3NDM5MTQ6MToxOmF0OjE'
```

**Step 5: POST oauth2/token - refresh token**

A refresh token allows an application to obtain a new access token without prompting the user. You can create a refresh token by making a POST request to the following endpoint: [https://api.x.com/2/oauth2/token](https://api.x.com/2/oauth2/token) You will need to add in the `Content-Type` of `application/x-www-form-urlencoded` via a header. In addition, you will also need to pass in your refresh\_token, set your grant\_type to be a `refresh_token`, and define your `client_id`.

This request will work for public clients:

```json theme={null}
POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token=bWRWa3gzdnk3WHRGU1o0bmRRcTJ5VUxWX1lZTDdJSUtmaWcxbTVxdEFXcW5tOjE2MjIxNDc3NDM5MTQ6MToxOnJ0OjE' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ'
```

Here is an example of one for confidential clients:

```json theme={null}
POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='\
--data-urlencode 'refresh_token=bWRWa3gzdnk3WHRGU1o0bmRRcTJ5VUxWX1lZTDdJSUtmaWcxbTVxdEFXcW5tOjE2MjIxNDc3NDM5MTQ6MToxOnJ0OjE'\
--data-urlencode 'grant_type=refresh_token'
```

**Step 6: POST oauth2/revoke - Revoke Token**

A revoke token invalidates an access token or refresh token. This is used to enable a "log out" feature in clients, allowing you to clean up any security credentials associated with the authorization flow that may no longer be necessary. The revoke token is for an App to revoke a token and not a user. You can create a revoke token request by making a POST request to the following URL if the App wants to programmatically revoke the access given to it:

```
https://api.x.com/2/oauth2/revoke
```

You will need to pass in the `Content-Type` of `application/x-www-form-urlencoded` via a header, your token, and your client\_id.

In some cases, a user may wish to revoke access given to an App, they can revoke access by visiting the [connected Apps page](https://x.com/settings/connected_apps).

```bash theme={null}
curl --location --request POST 'https://api.x.com/2/oauth2/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=Q0Mzb0VhZ0V5dmNXSTEyNER2MFNfVW50RzdXdTN6STFxQlVkTGhTc1lCdlBiOjE2MjIxNDc3NDM5MTQ6MToxOmF0OjE' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ'
```

This request will work for confidential clients:

```bash theme={null}
curl --location --request POST 'https://api.x.com/2/oauth2/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='\
--data-urlencode 'token=Q0Mzb0VhZ0V5dmNXSTEyNER2MFNfVW50RzdXdTN6STFxQlVkTGhTc1lCdlBiOjE2MjIxNDc3NDM5MTQ6MToxOmF0OjE'
```


# Authentication
Source: https://docs.x.com/fundamentals/authentication/overview

X APIs handle enormous amounts of data. The way we ensure this data is secured for developers and users alike is through authentication.

X APIs handle enormous amounts of data, and authentication secures that data for developers and users alike. You can choose from several authentication methods, listed below.

Most developers don't need to handle the complexities of authentication directly—client libraries take care of them automatically.

You can find a list of available client libraries on our [Tools and libraries](/resources/tools-and-libraries) page.

## Authentication methods

<CardGroup>
  <Card title="OAuth 1.0a User Context" href="/resources/fundamentals/authentication/oauth-1-0a/api-key-and-secret">
    OAuth 1.0a allows an authorized X developer App to access private account information or perform a X action on behalf of a X account.

    <br />

    [**Learn More**](/resources/fundamentals/authentication/oauth-1-0a/api-key-and-secret)
  </Card>

  <Card title="App only" href="/resources/fundamentals/authentication/oauth-2-0/overview">
    App only Access Token allows a X developer app to access information publicly available on X.

    <br />

    [**Learn More**](/resources/fundamentals/authentication/oauth-2-0/overview)
  </Card>

  <Card title="Basic authentication" href="/resources/fundamentals/authentication/basic-auth">
    Many of X's enterprise APIs require the use of HTTP Basic Authentication.

    <br />

    [**Learn More**](/resources/fundamentals/authentication/basic-auth)
  </Card>

  <Card title="OAuth 2.0 Authorization Code Flow with PKCE" href="/resources/fundamentals/authentication/oauth-2-0/authorization-code">
    OAuth 2.0 User Context allows you to authenticate on behalf of another account with greater control over an application's scope, and authorization flows across multiple devices.

    <br />

    [**Learn More**](/resources/fundamentals/authentication/oauth-2-0/authorization-code)
  </Card>
</CardGroup>

<Note>
  **Note:**
  You can get your App's API Keys, App-only Access Token, personal Access Token, and Access Token Secret from the [X developer Apps](/resources/fundamentals/developer-apps) section in the [Developer Console](/resources/fundamentals/developer-portal).

  **To make requests on behalf of another user**, generate a separate set of Access Tokens for that user using the [3-legged OAuth flow](https://developer.x.com/resources/fundamentals/authentication/obtaining-user-access-tokens), then pass that user's tokens with your OAuth 1.0a User Context or OAuth 2.0 user context requests.
</Note>

## Additional resources

<CardGroup>
  <Card title="Guides" href="/resources/fundamentals/authentication/guides">
    Learn how to generate tokens and authenticate requests using our integration guides.
  </Card>

  <Card title="API reference" href="/resources/fundamentals/authentication/api-reference">
    Review our reference guides for our authentication endpoints.
  </Card>

  <Card title="Best practices" href="/resources/fundamentals/authentication/guides/authentication-best-practices">
    Make sure you protect yourself and understand the best practices for storing your keys and tokens.
  </Card>

  <Card title="FAQs" href="/resources/fundamentals/authentication/faq">
    Have a question? Visit our FAQs.
  </Card>
</CardGroup>


# Counting Characters
Source: https://docs.x.com/fundamentals/counting-characters

How X counts characters in Posts, including the 280-character limit, weighted code points, URL shortening, emoji and Unicode handling, and edge cases.

Posts on X can contain up to **280 characters**. However, not all characters count equally—emojis, URLs, and certain Unicode ranges have special counting rules.

***

## Character weights

X uses a weighted character counting system. Most characters count as 1, but some count as 2:

| Character type                     | Weight      | Max characters |
| :--------------------------------- | :---------- | :------------- |
| Latin, punctuation, common symbols | 1           | 280            |
| Emojis                             | 2           | 140 emojis     |
| CJK (Chinese, Japanese, Korean)    | 2           | 140 characters |
| Other Unicode                      | 2 (default) | Varies         |

<Tip>
  Use the open-source [twitter-text](https://github.com/twitter/twitter-text) library to accurately count characters in your app.
</Tip>

***

## Emoji counting

All emojis count as **2 characters**, regardless of complexity:

| Emoji       | Display           | Character count | Unicode           |
| :---------- | :---------------- | :-------------- | :---------------- |
| 👾          | Single emoji      | 2               | U+1F47E           |
| 🙋🏽        | With skin tone    | 2               | 🙋 + 🏽 modifier  |
| 👨‍🎤       | Combined with ZWJ | 2               | 👨 + ZWJ + 🎤     |
| 👨‍👩‍👧‍👦 | Family sequence   | 2               | 4 emojis + 3 ZWJs |

Zero-width joiners (ZWJ) combine emojis visually but don't add to the count.

***

## URL handling

All URLs are wrapped with `t.co` shortener and count as **23 characters**, regardless of the original length:

```
https://example.com                    → 23 characters
https://example.com/very/long/path     → 23 characters
```

<Note>
  This applies to any valid URL detected in post text.
</Note>

***

## Special cases

| Content                  | Counting rule                                                |
| :----------------------- | :----------------------------------------------------------- |
| **@mentions in replies** | Auto-populated @mentions at the start of replies don't count |
| **New @mentions**        | @mentions you add manually count normally                    |
| **Media**                | Attached media (via official clients) counts as 0 characters |
| **Hashtags**             | Count normally (# + tag text)                                |

***

## Text encoding

The X API requires **UTF-8** encoding. Character length is calculated using Unicode Normalization Form C (NFC).

Example with `café`:

| Form             | Bytes       | Characters |
| :--------------- | :---------- | :--------- |
| NFC (composed)   | `c a f é`   | 4          |
| NFD (decomposed) | `c a f e ́` | 5          |

X normalizes to NFC, so both encode to 4 characters.

***

## Implementation

Use the official [twitter-text](https://github.com/twitter/twitter-text) library for accurate character counting:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    import { parseTweet } from 'twitter-text';

    const result = parseTweet('Hello, world! 👋');
    console.log(result.weightedLength); // 16
    console.log(result.valid);          // true
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from twitter_text import parse_tweet

    result = parse_tweet('Hello, world! 👋')
    print(result.weightedLength)  # 16
    print(result.valid)           # True
    ```
  </Tab>
</Tabs>

The library handles all edge cases including emoji sequences, URL detection, and Unicode normalization.

***

## Resources

<CardGroup>
  <Card title="twitter-text library" icon="github" href="https://github.com/twitter/twitter-text">
    Official open-source library for text parsing.
  </Card>

  <Card title="Configuration file" icon="file-code" href="https://github.com/twitter/twitter-text/tree/master/config">
    Character weight definitions and Unicode ranges.
  </Card>
</CardGroup>


# Apps
Source: https://docs.x.com/fundamentals/developer-apps

Create and configure X developer apps to get API credentials, set OAuth 1.0a and OAuth 2.0 permissions, manage callback URLs, and rotate keys.

Apps are containers for your API credentials. Each app has its own keys, tokens, and settings.

***

## App credentials

When you create an app, you can generate these credentials:

| Credential                | Use case                                                                     |
| :------------------------ | :--------------------------------------------------------------------------- |
| **API Key & Secret**      | Authenticate with OAuth 1.0a. Used to sign requests or generate user tokens. |
| **Access Token & Secret** | Make requests on behalf of your own account (OAuth 1.0a).                    |
| **Client ID & Secret**    | Authenticate with OAuth 2.0. Used for authorization code flow.               |
| **Bearer Token**          | App-only authentication for public data endpoints.                           |

<Tip>
  Choose **OAuth 2.0** for new projects. It offers fine-grained scopes and is required for X API v2 user-context endpoints.
</Tip>

***

## Creating an app

<Steps>
  <Step title="Open the Developer Console">
    Go to [console.x.com](https://console.x.com) and sign in.
  </Step>

  <Step title="Click Create App">
    Enter a name, description, and use case for your app.
  </Step>

  <Step title="Generate credentials">
    After creation, generate the keys and tokens you need.
  </Step>

  <Step title="Store securely">
    Save credentials immediately—they're only shown once.
  </Step>
</Steps>

***

## App permissions (OAuth 1.0a)

OAuth 1.0a apps have three permission levels:

<Tabs>
  <Tab title="Read only">
    * View posts, users, and public data
    * Cannot post, like, or modify anything
    * Cannot access Direct Messages
  </Tab>

  <Tab title="Read and write">
    * All read permissions
    * Post and delete posts
    * Follow/unfollow users
    * Like and repost
    * Cannot access Direct Messages
  </Tab>

  <Tab title="Read, write, and DMs">
    * All read and write permissions
    * Send and read Direct Messages
  </Tab>
</Tabs>

<Note>
  Changing permissions requires users to re-authorize your app to get new tokens with the updated scope.
</Note>

***

## OAuth 2.0 app types

When configuring OAuth 2.0, select your app type:

| Type                    | Client       | Use case                                                 |
| :---------------------- | :----------- | :------------------------------------------------------- |
| **Web App**             | Confidential | Server-side applications that can securely store secrets |
| **Automated App / Bot** | Confidential | Bots and automated services running on servers           |
| **Native App**          | Public       | Mobile or desktop apps that can't secure secrets         |
| **Single Page App**     | Public       | Browser-based JavaScript apps                            |

**Confidential clients** receive a Client Secret. **Public clients** use PKCE only.

***

## Callback URLs

Callback URLs (redirect URIs) are required for OAuth flows. After a user authorizes your app, they're redirected to your callback URL with an authorization code.

### Requirements

* Add callback URLs to your app's allowlist in the Developer Console
* URLs must match exactly (including trailing slashes)
* Maximum of **10 callback URLs** per app
* Use `https://` in production
* For local development, use `http://127.0.0.1` (not `localhost`)

### Disallowed protocols

These protocols cannot be used: `javascript`, `data`, `file`, `ftp`, `mailto`, `telnet`, and other non-standard schemes.

<Accordion title="Full list of disallowed protocols">
  `vbscript`, `javascript`, `vbs`, `data`, `mocha`, `keyword`, `livescript`, `ftp`, `file`, `gopher`, `acrobat`, `callto`, `daap`, `itpc`, `itms`, `firefoxurl`, `hcp`, `ldap`, `mailto`, `mmst`, `mmsu`, `msbd`, `rtsp`, `mso-offdap`, `snews`, `news`, `nntp`, `outlook`, `stssync`, `rlogin`, `telnet`, `tn3270`, `shell`, `sip`
</Accordion>

***

## Best practices

<CardGroup>
  <Card title="Use separate apps" icon="layer-group">
    Create different apps for development, staging, and production.
  </Card>

  <Card title="Rotate credentials" icon="arrows-rotate">
    Regenerate keys periodically and if you suspect a compromise.
  </Card>

  <Card title="Minimal permissions" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-check.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=768533bde161ac68862de87449f011c3">
    Request only the permissions your app actually needs.
  </Card>

  <Card title="Monitor usage" icon="chart-simple">
    Check the Developer Console regularly to track API usage.
  </Card>
</CardGroup>

***

## Automated account labels

If your app runs a bot account, you can label it as automated:

1. Go to your bot account's **Settings**
2. Select **Your account** → **Automation**
3. Link your managing account

This builds trust with users and distinguishes your bot from spam.

***

## Troubleshooting

<Accordion title="Callback URL not approved error">
  Ensure your callback URL is exactly as registered in the Developer Console, including protocol and any trailing slashes. HTTP-encode the URL when passing it as a query parameter.

  ```json theme={null}
  {
    "errors": [{
      "code": 415,
      "message": "Callback URL not approved for this client application."
    }]
  }
  ```
</Accordion>

<Accordion title="App suspended">
  If your app shows as suspended, check your email for a notice from the X platform team. Use the [Platform Help Form](https://help.x.com/forms/platform) to appeal.
</Accordion>


# Developer Console
Source: https://docs.x.com/fundamentals/developer-portal

Use the X Developer Console to manage projects and apps, monitor API usage, access credentials, invite team members, and view billing information.

The [Developer Console](https://console.x.com) is your central hub for managing X API access. Create apps, generate credentials, monitor usage, and manage billing—all in one place.

<Button href="https://console.x.com">Open Developer Console</Button>

***

## What you can do

<CardGroup>
  <Card title="Create & manage apps" icon="grid-2">
    Set up apps to get API credentials. Configure authentication, permissions, and callback URLs.
  </Card>

  <Card title="Monitor usage & costs" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143">
    Track API usage in real-time. View costs per endpoint and manage your credit balance.
  </Card>

  <Card title="Generate credentials" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5">
    Create API keys, access tokens, and OAuth credentials for your apps.
  </Card>

  <Card title="Purchase credits" icon="credit-card">
    Buy credits for pay-per-usage billing. No subscriptions or commitments required.
  </Card>
</CardGroup>

***

## Getting started

<Steps>
  <Step title="Sign up for a developer account">
    Go to [console.x.com](https://console.x.com) and sign in with your X account. Accept the Developer Agreement.
  </Step>

  <Step title="Create your first app">
    Click **New App** and provide a name and description. This generates your API credentials.
  </Step>

  <Step title="Save your credentials">
    Copy and securely store your API Key, API Secret, and Access Tokens. These won't be shown again.
  </Step>

  <Step title="Start building">
    Use your credentials to authenticate API requests. Check out the [quickstart guide](/x-api/getting-started/make-your-first-request).
  </Step>
</Steps>

<Warning>
  **Store credentials securely.** API keys and tokens are only displayed once when generated. Use a password manager or secure vault. If lost, you'll need to regenerate them, which invalidates the old credentials.
</Warning>

***

## Billing & credits

The X API uses pay-per-usage pricing with a credit-based system:

| Feature                  | Description                                                    |
| :----------------------- | :------------------------------------------------------------- |
| **No monthly fees**      | Pay only for what you use—no subscriptions                     |
| **Credit-based**         | Purchase credits upfront, deducted as you use the API          |
| **Real-time tracking**   | Monitor usage and costs in the console dashboard               |
| **Per-endpoint pricing** | Different endpoints have different costs                       |
| **Deduplication**        | Same resource requested twice in 24 hours is only charged once |

View current pricing and purchase credits in the [Developer Console](https://console.x.com).

[Learn more about pricing →](/x-api/getting-started/pricing)

***

## Team management

<Note>
  Team management is available for **Enterprise accounts** only.
</Note>

Enterprise accounts can invite team members to collaborate:

| Role              | Capabilities                                               |
| :---------------- | :--------------------------------------------------------- |
| **Administrator** | Full access: manage apps, billing, team members, and roles |
| **Developer**     | Manage own apps, read-only access to team apps             |

To invite a team member, navigate to the Team page in your console and enter their X handle.

***

## Next steps

<CardGroup>
  <Card title="Create an app" icon="plus" href="/resources/fundamentals/developer-apps">
    Learn about app settings, permissions, and credentials.
  </Card>

  <Card title="Make your first request" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/getting-started/make-your-first-request">
    Use your credentials to call the API.
  </Card>
</CardGroup>


# Rate Limits
Source: https://docs.x.com/fundamentals/rate-limits

Understand X API rate limits across access tiers and endpoints, including app-level vs user-level limits, response headers, and best practices for retries.

Rate limits control how many API requests you can make in a given time period. They ensure fair usage and system stability across the platform.

***

## Rate limits by product

Each X API product has its own rate limiting approach:

<CardGroup>
  <Card title="X API v2" icon="square-x-twitter" href="/x-api/fundamentals/rate-limits">
    Per-endpoint limits based on 15-minute windows. View detailed tables and recovery tips.
  </Card>

  <Card title="Enterprise API" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bank.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=6dd9ad48fa88936abb112b49e022abff" href="/x-api/enterprise-gnip-2.0/fundamentals/rate-limits">
    Custom limits based on your enterprise agreement and data package.
  </Card>

  <Card title="X Ads API" icon="rectangle-ad" href="/x-ads-api/fundamentals/rate-limiting">
    Limits specific to ad management and analytics endpoints.
  </Card>
</CardGroup>

***

## How rate limits work

| Concept               | Description                                             |
| :-------------------- | :------------------------------------------------------ |
| **Time window**       | Most limits reset every 15 minutes                      |
| **Per-user limits**   | Apply when using OAuth 1.0a or OAuth 2.0 user tokens    |
| **Per-app limits**    | Apply when using Bearer Token (app-only) authentication |
| **Endpoint-specific** | Each endpoint has its own limit                         |

***

## Checking your limits

Every API response includes headers showing 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 in the current window |
| `x-rate-limit-remaining` | Requests remaining in the current window       |
| `x-rate-limit-reset`     | Unix timestamp when the limit resets           |

***

## Rate limit errors

When you exceed a rate limit, you'll receive a **429 Too Many Requests** response:

```json theme={null}
{
  "errors": [{
    "code": 88,
    "message": "Rate limit exceeded"
  }]
}
```

***

## Best practices

<CardGroup>
  <Card title="Cache responses" icon="database">
    Store API responses locally to reduce repeated requests for the same data.
  </Card>

  <Card title="Use exponential backoff" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-history.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=6afe17587c08ee621e37afde19a07ff1">
    When rate limited, wait before retrying. Double the wait time with each retry.
  </Card>

  <Card title="Check headers" icon="list-check">
    Monitor rate limit headers to avoid hitting limits proactively.
  </Card>

  <Card title="Use streaming" icon="signal-stream">
    For real-time data, use filtered stream instead of polling search endpoints.
  </Card>
</CardGroup>

***

## Next steps

For detailed rate limit tables by endpoint, see the rate limits page for your specific API:

* [X API v2 Rate Limits](/x-api/fundamentals/rate-limits)
* [X Ads API Rate Limits](/x-ads-api/fundamentals/rate-limiting)


# Security
Source: https://docs.x.com/fundamentals/security

Security best practices for X API developers, including credential storage, OAuth handling, key rotation, secure callbacks, and vulnerability disclosure.

Building secure applications protects both your users and the X platform. This guide covers essential security practices for X API developers.

***

## Core requirements

<CardGroup>
  <Card title="TLS required" icon="lock">
    All API requests must use HTTPS. Plain HTTP is rejected.
  </Card>

  <Card title="Credential security" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5">
    Never expose API keys or tokens in client-side code, logs, or repositories.
  </Card>
</CardGroup>

***

## Protecting credentials

Your API keys and tokens are the keys to your app. Keep them secure:

<Steps>
  <Step title="Use environment variables">
    Store credentials in environment variables, not in code.

    ```bash theme={null}
    export X_API_KEY="your-api-key"
    export X_API_SECRET="your-api-secret"
    ```
  </Step>

  <Step title="Never commit secrets">
    Add credential files to `.gitignore`. Use tools like `git-secrets` to prevent accidental commits.
  </Step>

  <Step title="Rotate regularly">
    Regenerate keys periodically and immediately if you suspect a compromise.
  </Step>

  <Step title="Use minimal permissions">
    Only request the OAuth scopes your app actually needs.
  </Step>
</Steps>

### If credentials are compromised

1. **Regenerate immediately** in the [Developer Console](https://console.x.com)
2. **Revoke old tokens** — regenerating automatically invalidates old credentials
3. **Audit usage** — check for unauthorized API activity
4. **Update your app** — deploy new credentials to all environments

***

## Application security

### Input validation

Never trust user input. Validate and sanitize all data before using it:

```python theme={null}
# Bad - vulnerable to injection
query = f"from:{user_input}"

# Good - validate input first
import re
if re.match(r'^[a-zA-Z0-9_]{1,15}$', user_input):
    query = f"from:{user_input}"
```

### Output encoding

Escape X API data before displaying in HTML to prevent XSS:

```javascript theme={null}
// Bad - vulnerable to XSS
element.innerHTML = tweet.text;

// Good - escape HTML
element.textContent = tweet.text;
```

### Common vulnerabilities to prevent

| Vulnerability      | Prevention                                                  |
| :----------------- | :---------------------------------------------------------- |
| **XSS**            | Escape all user-generated content before rendering          |
| **CSRF**           | Use anti-CSRF tokens in forms; verify OAuth state parameter |
| **SQL Injection**  | Use parameterized queries, never concatenate user input     |
| **Open redirects** | Validate callback URLs against an allowlist                 |

***

## OAuth security

### State parameter

Always use the `state` parameter in OAuth flows to prevent CSRF:

```python theme={null}
import secrets

# Generate state before authorization
state = secrets.token_urlsafe(32)
session['oauth_state'] = state

# Verify state after callback
if request.args.get('state') != session.get('oauth_state'):
    abort(403)  # State mismatch - possible CSRF
```

### Token storage

| Token type         | Storage recommendation                             |
| :----------------- | :------------------------------------------------- |
| **Access tokens**  | Encrypted database or secure vault                 |
| **Refresh tokens** | Encrypted database with additional access controls |
| **Bearer tokens**  | Environment variables or secure configuration      |

***

## Secure development practices

<CardGroup>
  <Card title="Security audits" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834">
    Conduct regular security reviews and penetration testing.
  </Card>

  <Card title="Dependency scanning" icon="box">
    Keep dependencies updated. Use tools to detect vulnerable packages.
  </Card>

  <Card title="Logging" icon="file-lines">
    Log security events but never log credentials or sensitive data.
  </Card>

  <Card title="Monitoring" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143">
    Set up alerts for unusual API usage patterns.
  </Card>
</CardGroup>

***

## Reporting security issues

If you discover a security vulnerability affecting X:

<Warning>
  **Report within 48 hours.** X Developer Platform users must notify X no more than 48 hours after suspecting a security incident.
</Warning>

<CardGroup>
  <Card title="X Bug Bounty" icon="bug" href="https://hackerone.com/twitter">
    Report vulnerabilities in X's systems through HackerOne.
  </Card>

  <Card title="Your app incident" icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" href="https://hackerone.com/twitter">
    If your app using X data is breached, report through the same channel.
  </Card>
</CardGroup>

***

## Compliance checklist

<Accordion title="Security requirements for X API developers">
  * [ ] All API requests use TLS/HTTPS
  * [ ] Credentials stored securely (not in code or logs)
  * [ ] User tokens encrypted at rest
  * [ ] Input validation on all user-supplied data
  * [ ] Output encoding to prevent XSS
  * [ ] CSRF protection on OAuth flows
  * [ ] Security logging enabled (without sensitive data)
  * [ ] Incident response plan documented
  * [ ] Dependencies regularly updated
  * [ ] Minimal OAuth scopes requested
</Accordion>

***

## Resources

<CardGroup>
  <Card title="Authentication guide" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/resources/fundamentals/authentication/overview">
    Implement OAuth correctly.
  </Card>

  <Card title="App permissions" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-check.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=768533bde161ac68862de87449f011c3" href="/resources/fundamentals/developer-apps#app-permissions">
    Configure minimal required permissions.
  </Card>
</CardGroup>


# X IDs
Source: https://docs.x.com/fundamentals/x-ids

Understand 64-bit Snowflake IDs in the X API for Posts and users, including format, ordering, ID inflation, and safe handling in JavaScript clients.

Every object in the X API—posts, users, lists, DMs, spaces—has a unique ID. Understanding how these IDs work helps you build reliable integrations.

***

## ID format

X IDs are **64-bit unsigned integers** generated using a system called "Snowflake." Each ID encodes:

* **Timestamp** — When the object was created
* **Worker number** — Which server generated the ID
* **Sequence number** — Order within that millisecond

This means IDs are roughly time-ordered: higher IDs generally represent newer objects.

<Tip>
  IDs are globally unique across all of X, not just within a single object type.
</Tip>

***

## String vs. integer representation

<Warning>
  **Always use string IDs in your code.** Some programming languages (like JavaScript) can't accurately represent 64-bit integers.
</Warning>

In JavaScript, integers are limited to 53 bits. This causes precision loss with large IDs:

```javascript theme={null}
// This loses precision!
const id = 10765432100123456789;
console.log(id.toString()); // "10765432100123458000" — wrong!

// Use strings instead
const id = "10765432100123456789";
console.log(id); // "10765432100123456789" — correct!
```

### API versions

| Version        | ID format                                                               |
| :------------- | :---------------------------------------------------------------------- |
| **X API v2**   | IDs are returned as strings by default                                  |
| **X API v1.1** | Returns both `id` (integer) and `id_str` (string) — always use `id_str` |

***

## Working with IDs

### Storing IDs

Store IDs as strings or 64-bit integers in your database:

| Database   | Recommended type                        |
| :--------- | :-------------------------------------- |
| PostgreSQL | `BIGINT` or `TEXT`                      |
| MySQL      | `BIGINT UNSIGNED` or `VARCHAR(20)`      |
| MongoDB    | String                                  |
| SQLite     | `TEXT` (SQLite integers max at 63 bits) |

### Comparing IDs

When comparing IDs for chronological ordering:

```python theme={null}
# Python - safe for 64-bit integers
if int(id1) > int(id2):
    print("id1 is newer")

# JavaScript - compare as strings (lexicographically works for same-length IDs)
# Or use BigInt
if (BigInt(id1) > BigInt(id2)) {
    console.log("id1 is newer");
}
```

***

## Common ID types

| Object       | Example ID            | Notes                              |
| :----------- | :-------------------- | :--------------------------------- |
| Post (Tweet) | `1234567890123456789` | Also called Tweet ID               |
| User         | `2244994945`          | Older accounts have shorter IDs    |
| List         | `1234567890`          |                                    |
| Space        | `1YqGodQbNXDxv`       | Alphanumeric, not Snowflake format |
| DM Event     | `1234567890123456789` |                                    |

***

## Related resources

<CardGroup>
  <Card title="Data Dictionary" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/fundamentals/data-dictionary">
    See ID fields for each object type.
  </Card>

  <Card title="Post Lookup" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/lookup/introduction">
    Retrieve posts by ID.
  </Card>
</CardGroup>


# Important Resources
Source: https://docs.x.com/important-resources

Bookmark key X API documentation, SDKs, Postman collections, support channels, status pages, and community resources for developers building on X.

Bookmark these essential resources for X API development.

***

## Documentation

<CardGroup>
  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/introduction">
    Complete endpoint documentation with parameters and examples.
  </Card>

  <Card title="Data Dictionary" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/fundamentals/data-dictionary">
    Object schemas for posts, users, media, and more.
  </Card>

  <Card title="Authentication" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/resources/fundamentals/authentication/overview">
    OAuth 1.0a and OAuth 2.0 implementation guides.
  </Card>

  <Card title="Rate Limits" icon="gauge-high" href="/x-api/fundamentals/rate-limits">
    Per-endpoint limits and best practices.
  </Card>
</CardGroup>

***

## Tools

| Tool                                                                                                                                         | Description                           |
| :------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |
| [Developer Console](https://console.x.com)                                                                                                   | Manage apps, credentials, and billing |
| [Postman Collection](https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80) | Interactive API testing               |
| [Python SDK](/xdks/python/overview)                                                                                                          | Official Python library               |
| [TypeScript SDK](/xdks/typescript/overview)                                                                                                  | Official TypeScript library           |
| [OpenAPI Spec](https://api.x.com/2/openapi.json)                                                                                             | Machine-readable API specification    |

***

## Learning

<CardGroup>
  <Card title="Tutorials" icon="graduation-cap" href="/tutorials">
    Step-by-step guides for common use cases.
  </Card>

  <Card title="Sample Code" icon="github" href="https://github.com/xdevplatform">
    Example apps and code samples.
  </Card>

  <Card title="What to Build" icon="lightbulb" href="/x-api/what-to-build">
    Ideas and inspiration for projects.
  </Card>

  <Card title="Migration Guide" icon="route" href="/x-api/migrate/overview">
    Upgrade from v1.1 to v2.
  </Card>
</CardGroup>

***

## Community and support

<CardGroup>
  <Card title="Developer Forum" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=ce6313d8c0b7b4e5363f2ce80b89f7e4" href="https://devcommunity.x.com">
    Ask questions and share solutions with the community.
  </Card>

  <Card title="Support Hub" icon="circle-question" href="https://developer.x.com/en/support">
    FAQs, troubleshooting, and contact options.
  </Card>

  <Card title="@XDevelopers" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-logo-x.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=53e3153f3b8d6efdad31484ef133b274" href="https://x.com/XDevelopers">
    Official updates and announcements.
  </Card>

  <Card title="@API" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-logo-x.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=53e3153f3b8d6efdad31484ef133b274" href="https://x.com/api">
    API-specific news and tips.
  </Card>
</CardGroup>

***

## Stay updated

| Resource                                                             | What you'll get                        |
| :------------------------------------------------------------------- | :------------------------------------- |
| [Changelog](/changelog)                                              | All platform changes and updates       |
| [Changelog RSS feed](https://docs.x.com/changelog/rss.xml)           | Changelog updates for your feed reader |
| [Newsletter](/newsletter)                                            | Monthly roundup of news and features   |
| [Forum Announcements](https://devcommunity.x.com/c/announcements/22) | Important platform notices             |
| [API Status](https://developer.x.com/status)                         | Real-time service availability         |

<Tip>
  Follow [@XDevelopers](https://x.com/XDevelopers) and turn on notifications to catch breaking changes and new features.
</Tip>

***

## Quick reference

### Response structure

All v2 responses follow this structure:

```json theme={null}
{
  "data": { ... },      // Primary object(s)
  "includes": { ... },  // Expanded objects (if requested)
  "meta": { ... },      // Pagination info
  "errors": [ ... ]     // Partial errors (if any)
}
```

### Common parameters

| Parameter          | Use                          |
| :----------------- | :--------------------------- |
| `tweet.fields`     | Request specific post fields |
| `user.fields`      | Request specific user fields |
| `expansions`       | Include related objects      |
| `max_results`      | Limit results per page       |
| `pagination_token` | Get next/previous page       |

### Authentication methods

| Method       | Use case                                |
| :----------- | :-------------------------------------- |
| Bearer Token | Read-only public data                   |
| OAuth 2.0    | User actions with fine-grained scopes   |
| OAuth 1.0a   | User actions (legacy, full permissions) |

[Full authentication guide →](/resources/fundamentals/authentication/overview)


# X Developer Platform incident history
Source: https://docs.x.com/incidents

Historical record of past incidents, outages, and service disruptions affecting the X API v2, Enterprise APIs, Ads API, and streaming endpoints.

This page records past incidents affecting the X Developer Platform. For live service status, see the [X Developer Platform status page](https://developer.x.com/status).

## July 2026

<Steps>
  <Step title="OAuth2.0 login and /2/users/me - Outage / 401 error(s)" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **June 30, 23:00 UTC - July 1, 01:00 UTC**
  </Step>
</Steps>

## June 2026

<Steps>
  <Step title="X site-wide outage: API endpoint degradation" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **June 22, 12:00 UTC - 15:41 UTC**
  </Step>

  <Step title="Outage: Recent Search (/2/tweets/search/recent)" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **June 17, 02:20 UTC - 03:45 UTC**
  </Step>
</Steps>

## April 2026

<Steps>
  <Step title="Service outage: 503s /2/tweets" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **April 14, 21:00 UTC - 21:30 UTC**
  </Step>

  <Step title="Downstream outage: Streaming endpoints" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **April 1, 20:15 UTC - 20:30 UTC**
  </Step>
</Steps>

## March 2026

<Steps>
  <Step title="Service outage: Timeline API endpoints" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **March 31, 20:45 UTC - 21:00 UTC**
  </Step>

  <Step title="Missing entities.annotations" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident is ongoing. | **March 24, 02:00 UTC - Current**
  </Step>

  <Step title="Degraded new stream provisioning - Filtered Stream and XAA" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **March 27, 23:20 UTC - March 28, 00:56 UTC**
  </Step>

  <Step title="Increased webhook latency" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **March 24, 15:20:00 UTC - 18:00:00 UTC**
  </Step>
</Steps>

## February 2026

<Steps>
  <Step title="X site-wide outage: API endpoint degradation" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **February 16, 18:20 UTC - 19:50 UTC**
  </Step>

  <Step title="X site-wide outage: API endpoint degradation" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **February 16, 13:27 UTC - 14:29 UTC**
  </Step>
</Steps>

## January 2026

<Steps>
  <Step title="V2 Media Upload APIs - 404s" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **January 29, 04:00 UTC - 04:45 UTC**
  </Step>

  <Step title="V2 Streaming APIs - Increased latency" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **January 25, 17:00 UTC - 19:00 UTC**
  </Step>

  <Step title="Service-wide outage - Intermittent errors" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **January 24, 16:48 UTC - 20:30 UTC**
  </Step>

  <Step title="Streaming - 503 errors" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **January 23, 19:25 UTC - 20:30 UTC**
  </Step>

  <Step title="Service-wide outage - Intermittent errors" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **January 22, 17:30 UTC - 17:45 UTC**
  </Step>

  <Step title="Streaming endpoints - Increased connection errors / low volume" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **January 16, 15:39 UTC - 21:00 UTC**
  </Step>
</Steps>

## December 2025

<Steps>
  <Step title="V2 Streaming APIs - 503s" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **December 5, 7:00 UTC - October 15, 8:40 UTC**
  </Step>
</Steps>

## September 2025

<Steps>
  <Step title="404 errors - User Timeline (/2/users/:id/tweets)" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **September 10, 20:30 UTC - September 11, 04:30 UTC**
  </Step>

  <Step title="Increased latency - Volume & Firehose streams" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **September 10, 20:30 UTC - September 10, 22:00 UTC**
  </Step>
</Steps>

## August 2025

<Steps>
  <Step title="Developer portal issues" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **August 12, 01:00 UTC - August 12, 13:30 UTC**
  </Step>
</Steps>

## May 2025

<Steps>
  <Step title="500 errors - (Some X API endpoints may be affected)" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **June 26, 17:00 UTC - June 26, 17:45 UTC**
  </Step>

  <Step title="Google related outage - 503 errors for some endpoints" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been [resolved](https://downdetector.com/status/google/). | **June 12, 15:00 UTC - June 12, 23:00 UTC**
  </Step>

  <Step title="Site-wide outage (Some X API endpoints may be affected)" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **May 30, 20:20 UTC - May 30, 21:00 UTC**
  </Step>

  <Step title="POST /2/media/upload - 404 errors" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **May 30, 18:45 UTC - May 30, 21:00 UTC**
  </Step>

  <Step title="POST /2/media/upload - 404 errors" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **May 28, 17:00 UTC - May 28, 21:41 UTC**
  </Step>

  <Step title="Login with X (OAuth)" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **May 23, 17:35 UTC - May 27, 00:00 UTC**
  </Step>

  <Step title="Site-wide outage (Some X API endpoints may be affected)" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **May 22, 18:00 UTC**
  </Step>

  <Step title="Site-wide outage (All X API endpoints may be affected)" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **May 09, 05:00 - May 09, 07:00 UTC**
  </Step>
</Steps>

## April 2025

<Steps>
  <Step title="Filtered Stream Rules - 500 errors" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **Apr 02, 17:10 - Apr 02, 20:30 UTC**
  </Step>

  <Step title="Account Activity API outage" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **Apr 02, 13:09 - Apr 02, 13:51 UTC**
  </Step>
</Steps>

## March 2025

<Steps>
  <Step title="Site-wide outage (All X API endpoints may be affected)" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **Mar 10, 12:00 - Mar 11, 00:00 UTC**
  </Step>
</Steps>

## February 2025

<Steps>
  <Step title="Media metadata and subtitles v2 - 404 errors" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident is ongoing. | **Feb 6, 00:00**
  </Step>

  <Step title="Filtered Stream v2 - widespread 503 errors" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    Incident has been resolved. | **Feb 3, 17:30 - Feb 4, 01:00 UTC**
  </Step>
</Steps>

## January 2025

<Steps>
  <Step title="No incidents" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    There are no past incidents.
  </Step>
</Steps>

## December 2024

<Steps>
  <Step title="No incidents" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca">
    There are no past incidents.
  </Step>
</Steps>


# X Developer Platform Livestreams
Source: https://docs.x.com/livestreams

Watch recordings of X Developer Platform livestreams, including product walkthroughs, technical deep dives, AMA sessions, and integration tutorials.

View recordings and replays of previous broadcasts about the X Developer Platform, designed to help the developer community learn and build with our tools.

These include deep dives, getting started guides, and more.

## Past broadcasts

<BroadcastCarousel />


# Make Your First Request
Source: https://docs.x.com/make-your-first-request

Send your first X API v2 request in minutes using cURL or Postman, including authentication, endpoint selection, and parsing the JSON response.

This guide walks you through making your first X API request. You'll need a [developer account with app credentials](/x-api/getting-started/getting-access) before starting.

***

## Quick start with cURL

The fastest way to test the API is with cURL. Let's look up a user:

```bash theme={null}
curl "https://api.x.com/2/users/by/username/xdevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

Replace `$BEARER_TOKEN` with your actual Bearer Token. You'll get a response like:

```json theme={null}
{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "xdevelopers"
  }
}
```

***

## Step-by-step guide

<Steps>
  <Step title="Get your Bearer Token">
    In the [Developer Console](https://console.x.com), navigate to your app and copy the Bearer Token.
  </Step>

  <Step title="Choose an endpoint">
    Start with one of these beginner-friendly endpoints:

    | Endpoint                                          | What it does                       |
    | :------------------------------------------------ | :--------------------------------- |
    | [User lookup](/x-api/users/lookup/introduction)   | Get user profile by username or ID |
    | [Post lookup](/x-api/posts/lookup/introduction)   | Get post by ID                     |
    | [Recent search](/x-api/posts/search/introduction) | Search posts from the last 7 days  |
  </Step>

  <Step title="Make the request">
    Use cURL, Postman, or your preferred HTTP client:

    ```bash theme={null}
    # Look up a user by username
    curl "https://api.x.com/2/users/by/username/xdevelopers" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```
  </Step>

  <Step title="Parse the response">
    Responses are JSON. The primary data is in the `data` field:

    ```json theme={null}
    {
      "data": {
        "id": "2244994945",
        "name": "X Developers",
        "username": "xdevelopers"
      }
    }
    ```
  </Step>
</Steps>

***

## Request more data with fields

By default, endpoints return minimal fields. Use the `fields` parameter to request additional data:

```bash theme={null}
curl "https://api.x.com/2/users/by/username/xdevelopers?user.fields=created_at,description,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

Response:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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
    }
  }
}
```

[Learn more about fields →](/x-api/fundamentals/fields)

***

## More examples

<Tabs>
  <Tab title="Look up a post">
    ```bash theme={null}
    curl "https://api.x.com/2/tweets/1460323737035677698?tweet.fields=created_at,public_metrics" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```
  </Tab>

  <Tab title="Search recent posts">
    ```bash theme={null}
    curl "https://api.x.com/2/tweets/search/recent?query=from:xdevelopers&tweet.fields=created_at" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```
  </Tab>

  <Tab title="Get user's posts">
    ```bash theme={null}
    curl "https://api.x.com/2/users/2244994945/tweets?max_results=5" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```
  </Tab>
</Tabs>

***

## Using code instead of cURL

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import requests

    bearer_token = "YOUR_BEARER_TOKEN"
    url = "https://api.x.com/2/users/by/username/xdevelopers"

    headers = {"Authorization": f"Bearer {bearer_token}"}
    response = requests.get(url, headers=headers)

    print(response.json())
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const bearerToken = "YOUR_BEARER_TOKEN";
    const url = "https://api.x.com/2/users/by/username/xdevelopers";

    fetch(url, {
      headers: { Authorization: `Bearer ${bearerToken}` }
    })
      .then(res => res.json())
      .then(data => console.log(data));
    ```
  </Tab>

  <Tab title="Official SDKs">
    For production use, we recommend the official SDKs:

    * [Python SDK](/xdks/python/overview)
    * [TypeScript SDK](/xdks/typescript/overview)

    They handle authentication, pagination, and rate limiting automatically.
  </Tab>
</Tabs>

***

## Tools for testing

<CardGroup>
  <Card title="Postman" icon="server" href="/tutorials/postman-getting-started">
    Visual API testing with our collection.
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Examples in multiple languages.
  </Card>

  <Card title="API reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/lookup/introduction">
    Full endpoint documentation.
  </Card>
</CardGroup>

***

## Troubleshooting

<Accordion title="401 Unauthorized">
  * Check that your Bearer Token is correct
  * Ensure the token hasn't been regenerated
  * Verify the `Authorization` header format: `Bearer YOUR_TOKEN`
</Accordion>

<Accordion title="403 Forbidden">
  * Your app may not have access to this endpoint
  * Some endpoints require user-context authentication (OAuth 1.0a or 2.0)
  * Check your app's permissions in the Developer Console
</Accordion>

<Accordion title="429 Too Many Requests">
  * You've hit a rate limit
  * Check the `x-rate-limit-reset` header for when to retry
  * Implement exponential backoff in your code
</Accordion>

[Full error reference →](/x-api/fundamentals/response-codes-and-errors)

***

## Next steps

<CardGroup>
  <Card title="Learn authentication" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/resources/fundamentals/authentication/overview">
    Understand OAuth for user-context requests.
  </Card>

  <Card title="Explore endpoints" icon="compass" href="/x-api/posts/search/introduction">
    Discover what you can build.
  </Card>

  <Card title="Use an SDK" icon="cube" href="/tools-and-libraries">
    Faster development with official libraries.
  </Card>

  <Card title="Build something" icon="hammer" href="/x-api/what-to-build">
    Ideas for what to create.
  </Card>
</CardGroup>


# Subscribe to developer news
Source: https://docs.x.com/newsletter

Subscribe to the X Developer Platform newsletter for product updates, new endpoints, deprecations, events, and other news for API developers.

Sign up for emails about the latest news, product updates, and events from the X Developer team.

<Form />


# X Developer Platform
Source: https://docs.x.com/overview

Build, analyze, and innovate with X's real-time global data. Access posts, users, trends, and more through modern APIs with flexible pay-per-usage pricing.

## Products

Choose the access level that fits your needs.

<CardGroup>
  <Card title="X API — Pay-per-use" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-coins.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=d8b17de3fb4032d86b77606ea95fcb55" href="/x-api/introduction">
    Credit-based pricing with no commitments. Pay only for what you use.
  </Card>

  <Card title="X API — Enterprise" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bank.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=6dd9ad48fa88936abb112b49e022abff" href="/enterprise-api/introduction">
    High-volume endpoints, dedicated account management, and custom rate limits.
  </Card>
</CardGroup>

<Tip>
  Earn free [xAI API](https://docs.x.ai) credits when you purchase X API credits — up to 20% back based on your spend. [Learn more](/x-api/getting-started/pricing#free-xai-api-credits)
</Tip>

***

## Get started

<div>
  <Card title="Pay Per Use Pricing Changes: Featuring Owned Reads" icon="bolt">
    <div>
      <div>
        <img alt="X logo" />
      </div>

      <div>
        Owned Reads let you access your own data at reduced cost. Requests for your own posts, bookmarks, followers, likes, and more are priced at <span>\$0.001 per resource</span>.

        <br />

        <br />

        <Button href="/x-api/getting-started/pricing#owned-reads">Learn more</Button>
      </div>
    </div>
  </Card>
</div>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/getting-started/make-your-first-request">
    Get your API keys and make your first request in minutes.
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/introduction">
    Explore endpoints for posts, users, spaces, DMs, lists, and more.
  </Card>

  <Card title="SDKs" icon="cube" href="/tools-and-libraries">
    Official Python and TypeScript SDKs for faster development.
  </Card>
</CardGroup>

***

## Resources

<CardGroup>
  <Card title="Tutorials" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/tutorials">
    Step-by-step guides for common use cases and integrations.
  </Card>

  <Card title="Tools & Libraries" icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-wrench.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=c3f1761285cd013a76037d1d537f10ed" href="/tools-and-libraries">
    Official SDKs and community libraries for every language.
  </Card>

  <Card title="Developer Forum" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=ce6313d8c0b7b4e5363f2ce80b89f7e4" href="https://devcommunity.x.com">
    Get help from the community and X team.
  </Card>

  <Card title="Agent Resources" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-ai-agents.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=53171c3a2a9432187cf705d13e24651b" href="/tools/ai">
    llms.txt, skill.md, MCP servers, and resources for AI-powered development.
  </Card>
</CardGroup>

***

## Other products

<CardGroup>
  <Card title="X Ads API" icon="rectangle-ad" href="/x-ads-api/introduction">
    Programmatically manage ad campaigns, targeting, creatives, and analytics.
  </Card>
</CardGroup>


# Success Stories
Source: https://docs.x.com/success-stories

Customer success stories from developers and businesses building with the X API, including case studies across marketing, research, healthcare, and finance.

Companies and individuals all over the world have used the X Developer Platform to creatively innovate, gain valuable insights, and shape the future.

## Browse success stories


# Banco Pichincha x X
Source: https://docs.x.com/success-stories/audiense-banco-pichincha

How Banco Pichincha used X advertising and Audiense audience intelligence to boost sponsorship results and engage Ecuadorian football fans.

## How enhanced targeting enhances success

Sponsorships are no longer just a tool to gain notoriety – when engaging audiences, they can also deepen connections between fans and brands through unique experiences.

This is the exact goal that Banco Pichincha had in mind when they developed *El Diez de la Trivia* and *Trivia de Oro* to enhance sponsorships with football teams such as *Liga Deportiva Universitaria de Quito*, *Barcelona SC*, and *Universidad Católica* and with the *Ecuadorian* cyclist Richard Carapaz, respectively.

Banco Pichincha is a leading Ecuadorian financial institution, controlling a 30% market share. It also has a presence in Spain, Colombia, Peru, Panama, and the United States.

The bank activates trivia quizzes during the Ecuadorian soccer championship and the great cycling tours to test fans on their knowledge. They offer a way for fans to experience unique moments through prizes that range from signed shirts to meetings with athletes to attendance at training sessions.

## Challenges and goals

These trivia quizzes have evolved since their inception, with many changes implemented to drive more participation: they adjusted the questions to make them easier and expanded the participation metric beyond Retweets to include Likes as a trigger.

They also added the option to share the trivia contest along with a predetermined text so they could encourage more people to participate.

However, Banco Pichincha’s initial audience target was too wide resulting in engagement tactics that weren’t reaching the right people.

## Solution

Banco Pichincha used [Audience Manager](https://help.audiense.com/knowledge/audience-manager), a network graph analysis function of [Audiense Connect](https://resources.audiense.com/blog/what-can-i-do-with-audiense-connect-twitter-marketing-plan), to create Custom Audiences of creators and amplifiers. This allowed them to focus their advertising with their unique audience more effectively.

> *“We talk to everyone: our brand audience and a whole lot more. But through media, we target only those creators and amplifiers that allow us to reach the audience we want.”*
>
> * Carlos Serra from Audiense

For the Richard Carapaz-themed trivia quiz, Banco Pichincha were able to create three distinct custom audiences:

1. An audience related to the sport i.e., people who are fond of cycling in Ecuador, people who are fans of Barcelona Universidad Catolica, etc.)
2. An audience of influencers for the first audience. These influencers helped with amplification through a bigger bid in the X ads campaign. This could only be done using graph segmentation and tailored audiences.
3. An audience of “followers of”: Utilizing the follower graph to identify relevant people in the world of cycling who were based in Ecuador. Audiense Connect helped them identify the 100 most relevant accounts and their followers, which they included in the following targeting.

<img alt="Campaign plan" />

Using the insights from Audiense, the banking institution was able to understand and analyze what their audience cared about to shape and evolve the trivia.

They identified the engagement metrics they could generate, which would allow them to take better advantage of sponsorships. This helped to generate a more meaningful connection with customers and fans of the team.

Banco Pichincha began running a paid campaign on X in August 2021. The campaign started on August 12, 2021 and involved 40,161 Tweets using the hashtags `#ElDiezDeLaTrivia` and `#LaTriviaDeOro` . Banco Pichincha used both the Retweet trigger and Likes trigger for engagement. From August 2021 to August 2022, the campaign saw almost 22,000 participants of the 28 trivia quizzes.

<img alt="Post 1" />

<img alt="Post 2" />

## Results

By increasing the relevance in targeting, Banco Pichincha was able to increase trivia participation by 10 times.

> *“Our ongoing data analysis, the formulation of growth hypotheses, and the execution of experiments to validate them, were key elements to maximize the power of the community, which is very active on X and follow our sponsored teams and athletes. The results of this exercise, along with a strategic segmentation, allowed us to grow from 366 unique users during the first trivia in August 2021, to 3291 in the last Richard Carapaz trivia, that took place last June 2022.”*
>
> * Patricia A. Villarruel Gordillo, Content Director at Banco Pichincha

From August 2021 to July 2022, they generated a total of 12,628,660 impressions at a CPM of €0.48 ($0.49 USD). They also collected 228,732 Tweet engagements at a cost per engagement of €0.11 ($0.11 USD), where engagements refer to the actions that fulfil the campaign objective. This may be an action such as watching a video in a promoted video views campaign.

### Conclusion

Whether it’s to drive more purchases or more trivia participation, conversions are the ultimate goal for any marketing campaign. To achieve this goal, you need to make sure that the right people come across your campaign. This is why fine-tuning segmentation to reach niche audiences, and why specific targeting, is so important for success.

Using a solution like Audiense Connect in combination with Twitter API can help you engage the right target with your content – to drive the success you’re looking for.

[Sign up today](https://dashboard.audiense.com/app/signup/connect) to build your tailored audiences.


# Canada Excellence Research Chair (CERC)
Source: https://docs.x.com/success-stories/cerc-academic-research

How researchers at the Canada Excellence Research Chair use the X API to study migration, refugees, and public discourse with full-archive social data.

<div>
  <div />

  <div>
    <div>
      Canada Excellence Research Chair (CERC)
    </div>

    <p>
      Using Twitter’s API to fuel academic research
    </p>
  </div>
</div>

<Note>
  **Here's the tl;dr**

  Learn how Stein Monteiro — research fellow for the Canada Excellence Research Chair (CERC) in Migration and Integration at Ryerson University — was able to use Twitter data to further his research on the relationship between the Indian diaspora and India during the farmers’ protests.

  For Stein Monteiro, the farmers’ protests in India presented an interesting question: how would the Indian diaspora act during a time when major events took place in India? With the help of Twitter’s API, he was able to uncover the answer. Read about it here.
</Note>

## Challenge

For Stein Monteiro — research fellow for the Canada Excellence Research Chair (CERC) in Migration and Integration at Ryerson University — work lies at the intersection of statistics, culture and current events. While his economics expertise set him up for success in academia, it was his own experience that fuelled a passion for migration studies.

Born and raised in India, Stein lived in Dubai during his high school years before heading to Canada for his undergraduate degree. For him, the feeling of being new to a country was deeply familiar. He was no stranger to the experience of navigating new social systems, climates and ways of life. The process of adjusting to new cultures and environments sparked his interest in the migrant integration journey. As he continued his studies in economics, the draw of these more personal experiences remained compelling — so he sought to combine both worlds. In order to obtain his PhD in economics, he focused his dissertation on migration studies literature.

While working on this dissertation, Stein taught himself how to code. When he later worked as a statistician for Humber College, he was able to put what he learned into practice. Coding enabled the process of automation — simplifying his work by organizing and crunching data.

By placing his work process into coding form, Stein was able to identify problems more easily and explain his work/thought process in a step-by-step manner to others. It opened up a whole new way of looking at a problem and building solutions. He was slowly realizing the unlimited potential of this skillset, and he took this knowledge with him to the Canada Excellence Research Chair (CERC).

While at CERC, Stein’s attention was captured by the online activism he witnessed all over social media, particularly around the Indian farmers’ protests (sparked by three controversial laws introduced in August, 2020). He could see connections between these protests and his work. This was an important moment: what was happening in real-time could reveal information about the migrant and diaspora experience as a whole.

As the conversation exploded around him, he wondered how online activism was affecting the activity of people in the Indian diaspora living in Canada, the UK, Australia, and the Gulf countries. How are social networks connecting migrants to the conversations in India?

It was time to get to work.

## Solution

In order to better understand the relationship between the Indian diaspora and their connection to the farmers’ protests, Stein knew he had to tune into the online conversation — so he set his sights on Twitter.

According to Stein, “these local events were able to cater to an international audience, not just because Twitter is an international phenomenon but also because people, just regular people, were able to speak to each other online, and they were able to connect with each other, just through a hashtag.” For him, with Twitter, “you can be a participant in the farmers' protests happening in India and not be Indian, or be Indian but be in a different part of the world.

Stein saw Twitter as the place involving the protestors, anti-protest rhetoric, pro-government entities, and unfiltered experiences of what was actually happening on the ground. And he wanted in on the action.

Absorbing the conversations, Stein needed to home in on a few things: when someone posts something online in India, how does that Tweet carry to the rest of the world? How does information flow through networks, hashtags etc.? And how is the diaspora responding to the Tweets coming in from India?

Stein was able to gain clarity with the help of Twitter’s API, which introduced the Academic Research product track, allowing access to historical data in addition to large volumes of Tweets and author information for further analysis.

To Stein, the power of the API was accessibility over a large period of time that would allow him to create a time dimension of conversations — who’s Retweeting what and who’s talking to whom.

With all this information at his disposal, he was shocked by what he found: there was an enormous level of activity from the Indian diaspora reacting to the situation in India. Stein says, “it wasn’t even delayed activity, it was almost immediate. So within the span of a day, I was seeing Retweets from people posting in India and then Retweets happening within the rest of the world.”

The data was clear: social media enables migrants and diasporas to stay connected to their home countries and play active roles in important conversations.

## Impact

Using Twitter’s open API, Stein was able to research a timely event that provided insight into the greater conversation of the migrant experience. Access to data and functions to filter and sort that data proved pivotal to this project.

More importantly, Stein recognized the importance of Twitter as a tool for academic research as a whole. For him, one of the biggest hurdles in research is that data needs to be gathered from across the globe. Fortunately, Twitter’s international presence provides this access to global information, without the need to spend lots of money on surveys and focus groups in various parts of the world.

Stein notes, “Twitter allows researchers and the academic community to access data for their own research purposes in a new way, to develop new methodologies, but also in a cost-efficient way.” He believes the conversations happening online were useful because “they were very unfiltered and they were unbiased conversations happening between people without the interference of the researcher in that conversation.”

Stein’s work proved that Twitter remains a tool for connection across the globe — while Twitter’s APIs can help gather large-scale insights that spring from that connection.

<video>
  <source type="video/mp4" />

  Your browser does not support the video tag.
</video>


# Decoding Hate
Source: https://docs.x.com/success-stories/decoding-hate

How the Decoding Hate project used the X API to analyze personal experiences of hate incidents during COVID-19 and surface patterns for researchers.

## Situation

Following the outbreak of COVID-19, there was a rise in hate incidents directed towards Asian Americans and Pacific Islanders (AAPIs). While some of these incidents were covered in the news, thousands of individuals were filing reports with the national reporting center [Stop AAPI Hate](https://stopaapihate.org/), which responds to and addresses hate incidents through research, advocacy, and capacity-building. During this time, [The American Asian Foundation (TAAF)](https://www.taaf.org/) was founded. This organization became the driving force behind the team that decided to leverage X to provide a new window into how these incidents are personally affecting the people targeted.

## Solution

The small team of two engineers looked to X as their source for incident data. They chose this platform for two reasons: firstly, it contains rich and diverse information, such as news, people's ideas, thoughts, daily life events, and things happening in their communities. Because of this, X offers a unique, intimate sample of various populations. X is also the only platform with a truly open API where the TAAF developers could access data and has in-depth tools to collect and analyze that data.

Using the X API v2 search Tweets and Tweets lookup endpoints, the team was able to search post statuses and identify when people reported a hate incident (and even what hashtags they would use). This helped the team design a 1023-character search query that narrowed the billions of posts down to an amount the team could work with.

Next came the task of verifying that the posts were indeed about hate incidents. The team developed a tool with natural language processing to help sift through thousands of posts to find ones relevant to the project. After applying their trained machine learning model, the posts were then verified by a human to further increase accuracy.

In 2021, TAAF also co-authored the [Documenting Anti-AAPI Hate Codebook](https://stopaapihate.org/wp-content/uploads/2021/12/SAH-x-TAAF-Codebook-FINAL-2021-08-19.pdf) with the Stop AAPI Hate coalition. This resource includes draft standards and practices for community-based data collection which helped the team classify incidents that people were sharing over X.

From there, the next challenge was to present this data in a way that people could easily digest. TAAF created a data visualization tool, [Decoding Hate](https://decodinghate.taaf.org/), that displays their vast amount of data in an interactive way. With the help of a data visualization studio, they were able to take the annotated X data and turn thousands of posts into insightful stories that expose the truth behind what was happening within AAPI communities.

## Impact

The Decoding Hate project helped detect thousands of hate-related incidents that were otherwise going unreported and continues to do so today. This project has become an ongoing tool for spreading awareness of the individual experiences taking place within the AAPI community.

For the next phase of work, TAAF will be partnering with Stop AAPI Hate to pilot individual human responses to individuals who report hate incidents on X. During this phase, Stop AAPI Hate will actively engage with many of the people sending posts discussing the hate they have experienced and encourage them to report the incidents through the [Stop AAPI Hate Reporting Center](https://stopaapihate.org/). The more people who report to Stop AAPI Hate, the better the coalition and its partners can understand the nature of hate incidents that are taking place and advocate for the most effective policy solutions.

Along with exposing the hate-related incidents going on in AAPI communities, the project also shines a light on the value of X’s API. This case shows us that by leveraging the right data with the right tools, developers can use X to innovate for a good cause.


# Flocknet
Source: https://docs.x.com/success-stories/flocknet

How Flocknet uses the X API to help users discover and reconnect with people in their network, surfacing meaningful relationships across the platform.

<Note>
  **Here's the tl;dr**

  Here’s how Aaron Ng—developer and creator— was able to use X’s API to build Flocknet, a search engine for your X network. People are using Flocknet to expand their networks, recruit talent, and source investment leads. Initially built for his own personal use, Flocknet is now helping people manage millions of contacts on X.
</Note>

## Challenge

When Aaron Ng attended a design conference in New York, he wanted to connect and meet with others in his industry. But that’s when he realized connecting, even with his own designer friends on X, was more challenging than he thought. Much of his community was on X, especially his friends in the industry. Was there no way for him to see which of his friends would be in town? How could he catch up with industry connections, without knowing who would be around?

Aaron immediately saw this challenge as an opportunity. And as a result of his entrepreneurial spirit, Flocknet was born.

## Solution

In just one weekend, Aaron was able to build a product for searching, sorting, and keeping up with people, friends, and other professionals in his X network, even without seeing their Tweets. He chose to use X’s API for this project, “knowing there’s someone I can ask questions to, and \[knowing the X] team cares, makes it a much nicer experience.” Adding, “much of the community that motivated me to keep building was on X — which is why it’s become such an important place to me, and why I wanted to make some tooling to enhance my usage of it.”

With a mix of his own creativity, drive, and experience, Flocknet came to life—a search engine and contact management tool for finding people in your X network. Utilizing X’s follows endpoints and Python, Flocknet allows users to search through their followers by job, workplace, location, and numerous other attributes.

While initially meant for his own personal use, Flocknet generated so much public interest, that he knew it was meant to be shared. As such, he quickly shifted his efforts to scale up Flocknet to be what it is today.

<img alt="" />

## Impact

In just a few short months, Flocknet manages millions of contacts on behalf of its users. Tech professionals have found it especially useful, using it for everything from recruiting to investing, and anything in between. In fact, even Aaron has hired people through Flocknet!

But Aaron’s not done, just yet. By focusing on the incoming feature requests, Aaron continuously looks for ways to build out the product.

Ultimately, Aaron found a way to turn X into a meta-platform to enhance the experience of anyone whose community primarily exists on X. He says, “I just make a lot of stuff. And I love making things that I find useful and other people find useful”. And that’s exactly what he did.


# GSK x Meltwater
Source: https://docs.x.com/success-stories/gsk-meltwater

How GSK and Meltwater used X API data to identify and activate healthcare professionals as influencers, expanding reach in regulated medical communities.

<Note>
  **Here's the tl;dr**

  We’re taking a closer look at how GSK Consumer Healthcare — a global British pharmaceutical company whose mission is to deliver better everyday health with humanity —  was able to reach healthcare professionals active on X, in an effort to establish these professionals as influencers. This case study highlights how Meltwater helped GSK zero in on the necessary X data to make this endeavor possible.
</Note>

## Situation

Both Influencer marketing and healthcare are ubiquitous in today’s society, but the two industries don’t often intersect. It was this gap that GSK — a British-based pharmaceutical company — sought to close.

As social media usage has continued to increase, healthcare companies are aware of the importance of meeting their audience where they are. And GSK saw the opportunity to tap into this new market to identify healthcare professionals for future collaborations and business opportunities. They also recognized X as the perfect social media platform for deeper insights.

The effort started with the online oral health space — GSK’s largest category at £2.7B in sales for fiscal year 2020. The goal was to capture interests among experts in the oral health space and determine the relationships between stakeholders. For example, during COVID-19, hygienists were more active and engaged on X than dentists. Due to the nature of their job, hygienists were at a much higher risk for infection — so they went online to give guidance on what was safe to do given the situation.

## Solution

The team at GSK knew that healthcare professions are well-represented on X. In order to tap into that data source, they turned to Meltwater — a platform with 10 years’ experience streamlining X’s breadth of information.

Using Meltwater’s search operators, GSK could specifically filter those who disclosed relevant professions in their bios and posts. Then, they expanded the search with specific keywords and phrases relevant to online dialogue in the field. Additional filters helped them zero in on organic conversations and trends across X, while cutting out irrelevant posts, reposts, and post replies.

## Impact

With the implementation of Meltwater's search operators, GSK saw a decrease in research turnaround time from 2 months to about 2-3 weeks. This report was formerly a time-intensive and bespoke process, which became more streamlined with the new operators. With less time spent on analysis, GSK was able to effectively reach 2.3K healthcare professionals.

Dentists and hygienists proactively post information for their followers and respond to individual questions, serving as the voice of reason for those inquiring about dental procedures.  For this reason, positioning them as influencers provides people with a trustworthy source of healthcare knowledge.

The saved search library in Meltwater Explore was a vital tool that gave GSK precision data from an on-demand community of healthcare professionals on X. It allowed for them to gather leading insights from young and more digitally-savvy professionals as they move from their healthcare training to become the next big players in the real world. The result was a blueprint that they’ve successfully applied across their 20+ US brands to help create groups of healthcare professionals for potential business partnership opportunities.

*Source: Meltwater Explore, Jan 2020 - Feb 2021, retrieved March 2021.*


# ListenFirst boosts efficiency with X API v2
Source: https://docs.x.com/success-stories/listenfirst-x-improving-efficiency

How ListenFirst used X API v2 to streamline data aggregation, improve accuracy, and deliver unified social analytics to marketing clients.

## Situation

Historically, digital marketers have lacked a unified view of their data. There could be organic data in one system, paid data in another, and conversations coming from different places. But with clients and stakeholders asking questions like, “How many impressions did I receive yesterday?” followed by “What is the organic vs paid split?,” the need for a streamlined way to aggregate and interpret this data is more important than ever.

Looking to solve these questions, ListenFirst - a social analytics platform that has been built with the X Developer Platform for over 10 years – needed to create a tool to collect organic and paid X data from a single source of truth. Historically, this organic and paid data lived in separate silos across different platforms, APIs and endpoints; and was certainly never meant to be aggregated, sumed and/or blended together.

## Solution

In the quest to find more efficient ways to drive insights for their clients, ListenFirst adopted X’s v2 endpoints to streamline their translation of what users are talking about on X into their platform. ListenFirst’s team got to work with one clear goal in place: to create cleaner data.

> *“For us, utilizing v2 is about integration optimization. If there are fewer pieces we have to put together on our site, it makes our operations easier and allows us to scale our offering to even more brands, more content and better insights.”*
>
> * Jonathan Farb, Chief Product Officer, ListenFirst.

What drove the team to prioritize the adoption of X’s v2 API, and specifically the Tweets lookup endpoint, was the accuracy of the engagement and impressions numbers. By utilizing this endpoint, ListenFirst was able to generate more reliable metrics that were aligned with what their customers saw on native X analytics elsewhere.

## Impact

While still in its infancy, adopting v2 has impacted ListenFirst’s efficiency. Historically, ListenFirst had to piece together data from various sets of APIs, and the numbers weren’t aligned with what was seen in native analytics. Their usage of v2 brings ListenFirst’s numbers closer to parity with X’s native analytics, improving accuracy and customer trust. Now, ListenFirst can produce defensible and refined intelligence to help brands complete their marketing strategy on X. ListenFirst believes that further adoption of v2 will drive confidence in client metrics by improving accuracy and transparency.


# Publicis x YouScan
Source: https://docs.x.com/success-stories/publicis-youscan

How Publicis Sport & Entertainment used YouScan and X API visual listening to surface sports marketing insights from images and brand mentions.

## Situation

Sponsorships and marketing strategies are the driving force behind sports brands today. Understanding how they work is key to discovering what consumers need and how they behave towards their products. They're a way to get a realistic view of the audience turnout for each sport, what kind of engagement different sponsorship activities bring to their competitors, and whether there is any strong association between sports audiences and sports brands. Publicis stepped up to the plate to help a major sports brand decide if including sports sponsorship activities in their marketing strategies.

## Solution

For this research, Publicis teamed up with YouScan – a social media intelligence platform with image recognition capabilities. Its visual insight technology allows users to analyze visual brand mentions and obtain advanced analytics thanks to artificial intelligence and machine learning. The platform identifies more than 1,000 scenes, objects, and activities along with demographic information to provide brands with in-depth analytics.

Using YouScan, Publicis analyzed 1.9 million images, targeting X as one of the main sources with more than 150k images (mentions). X is special because customers share their unbiased opinions, life moments, feedback and thoughts with the X community, helping brands receive a comprehensive overview of consumer behavior.

The agency used visual data as a foundation for this research and collected images featuring Nike, Adidas, Puma and Reebok logos in the US, UK, and Canada (coming from accounts with disclosed geo-location) over a two-month period (May-June 2022).

From there, YouScan’s analysis showed that around 22% of the mentions did not contain a word or hashtag with the brand and only contained a visual representation – including the brand logo or the brand name spelled somewhere in the visual (text recognition).

## Impact

Publicis’ research using YouScan allowed a major sports brand to identify its strategy for 2023 sponsorship activities, receiving detailed analytics on the number of unique images, engagement, and distribution that each of their competitors has in major sports.

<img alt="" />

After analyzing 1.9M images, more than 150k on X, 462M engagements and 901k authors, YouScan’s’ top five findings of the research were:

* Nike’s logo appeared in publications about different types of sports significantly more frequently than other brands (77.2%).
* Nike is the brand that generates the highest engagement (38.9M).
* Football (soccer) generates the most engagement for almost all sports brands (Nike, Adidas, Puma), making it the most effective sponsorship activity in terms of visibility.
* The top logo on helmets was Nike (84%). Adidas appeared on shorts (22%) and shirts (32%).
* The number of men featured (86.3%) significantly outnumbers the number of women (13.7%), so it hints at a potential CSR problem and an opportunity at the same time.

<img alt="" />

This is a great example of how analyzing consumer opinions, discovering actionable insights and managing brand reputation can keep brands relevant in daily trend discussions while putting the customer experience at the heart of the business.


# PublicSonar X Municipality of The Hague
Source: https://docs.x.com/success-stories/publicsonar

How PublicSonar and the Municipality of The Hague use X API social monitoring to improve traffic flow, public safety, and emergency response in real time.

<Note>
  **Here's the tl;dr**

  Here’s how the municipality of The Hague was able to increase mobility and safety of their roads through a partnership with PublicSonar — a company that helps organizations make informed decisions using AI-driven insights. Through leveraging social insights, PublicSonar provides additional information to help The Hague traffic control center act quickly and effectively to evolving road conditions.
</Note>

## Challenge

Across continents and time zones, traffic is an unpredictable, chaotic facet of daily life. It’s an experience shared across the world, impacting the lives of many. Efforts to regain control of the roads are constantly underway, yet few places have taken matters more seriously than the municipality of The Hague.

The Hague traffic control center invested in technology and intelligence tools like CCTVs and underground sensors, with the goal of providing quick, safe solutions and responses to the traffic-related incidents that inevitably arise in a large city. However, one challenge remained: how could they get the right information, in real time, in order to make the best decisions?

Despite their advanced technological toolkit, The Hague traffic control center was still missing some key information. In order to help fill those gaps, they turned to PublicSonar — a company that helps organizations make informed decisions by using AI-driven insights.

## Solution

The biggest hurdle to increasing mobility and providing safety is the ability to gain information from the ground. Fortunately, by partnering with PublicSonar, the municipality of The Hague was able to uncover the missing puzzle piece to traffic control: social media.

Enter X. X’s real-time conversations were pivotal in providing insights for PublicSonar to fill in information gaps.

For PublicSonar, the way in which X data is offered, and the stability and support from X's API, is crucial for their work. Through the use of keywords, they were able to filter information for traffic-related topics, which they used to create an easily digestible online dashboard for the Municipality of the Hague to utilize. Their value is finding the balance that avoids too many false positives that will overload the traffic control center, while also ensuring no important information is missed.

## Results

Through social media monitoring, PublicSonar provides The Hague with insights that allow them to make appropriate decisions during planned events (i.e concerts), typical situations (i.e. busy beach days), and incidents (i.e. car accidents).

Ultimately, both technology and social insights work hand in hand to create a clearer picture, with social media providing more “eyes on the road.” These streams of information keep the fingers of the traffic control center on the pulse of what’s happening, so that they can continue to provide The Hague with safer and smoother driving conditions.


# Red Cloud Financial Services
Source: https://docs.x.com/success-stories/red-cloud-financial

How Red Cloud Financial Services uses X API data to track market sentiment, surface trading signals, and inform investment research workflows.

<Note>
  **Here's the tl;dr**

  Trending towards success: When Red Cloud Financial Services was tasked with helping a mining company market their new green technology, it turned to Audiense’s targeting tools built on X analytics to mine the data and reach new audiences.
</Note>

## Situation

Red Cloud Financial Services was tasked with helping its client, a publicly-traded mining company, raise awareness about new patent-pending technology they had developed with a brand new audience.

The company had to find a way to drive results for this new product in order to transition into new territories and effectively run a campaign that would reach those new customers.

The ask posed two key challenges:

1. **Reach a new audience**

   Rather than focus on their existing mining customers, the client’s new technology appealed to a broader segment interested in green innovation and social responsibility. These were uncharted waters for Red Cloud, and nothing like the previous campaigns it had run.

2. **Provide a concrete ROI**

   The client was not accustomed to doing paid campaigns. The expectation for Red Cloud to spell out the ROI of an awareness-based campaign and produce results with an audience it had limited firsthand experience with was a daunting task.

   Red Cloud turned to Audiense to help reach current customers while researching prospective new ones. Audiense’s X marketing product specializes in delivering impactful X campaigns using its powerful audience targeting tools.

## Solution

Red Cloud began by setting expectations. Leveraging insights from Audiense to create campaign performance forecasts, Red Cloud was able to set the client’s expectations regarding the end-goals and associated KPIs of the campaign.

With help from Audiense, Red Cloud focused its research on X for mining company news and related stock information. Audiense’s platform made it easy to find potential correlations between the campaign and increased interest reflected by video views and increased website traffic.

A 3-tiered approach:

1. Build brand new audiences.

   Taking direction from its client, Red Cloud Financial identified two primary audiences to focus the campaigns on: the first segment included mining and investment, the second clean tech, electric vehicles, ESG and responsible investing. X's data further helped Red Cloud align those audiences with future campaigns.

2. Segment the new audiences.

   Although the new audiences covered a wide range of industries, there were plenty of common threads between them. Audiense helped Red Cloud Financial mine these new segments to identify influencers, content consumption habits and more. These insights also helped them determine which accounts to follow in hopes they would reciprocate and grow the Red Cloud and client audiences.

3. Determine which is most valuable.

   Determine which is most valuable. Using Audiense’s [Targeting Pack feature](https://help.audiense.com/knowledge/what-is-a-targeting-pack), Red Cloud created laser-targeted paid X ad campaigns, while using the accumulated data for X segments for organic campaigns. Leveraging insights derived from the Targeting Pack feature, Audiense and Red Cloud created two unique videos targeting the two audiences. They were able to determine which video was consistently the top-performing campaign and stay on track with their targeting.

## Impact

Audiense’s platform and their X research helped Red Cloud find the right audiences, segment them, leverage them to grow followers and inform its overall social media strategy for both organic and paid content.

Red Cloud Financial exceeded its client’s expectations. In fact, the results of the campaigns were so positive, the client decided to move forward and ramp up another one.

* The combined campaigns garnered 3.5+ million impressions and 2.8+ million total views
* There was a rise in conversation volume related to the client’s new patent-pending technology
* They noticed a boost in website referral traffic, including 7,000 new visitors from the promoted article and press release about their new technology

This is a prime example of how audience analytics and targeting on X can help you tap into new audiences, refine marketing campaigns and deliver real results. It can be a golden opportunity to help build your clients’ brands and boost their business.


# SMASH x Audiense
Source: https://docs.x.com/success-stories/smash-and-audiense

How SMASH and Audiense leveraged X API audience intelligence to identify valuable followers and expand brand reach with data-driven targeting.

<Note>
  **Here's the tl;dr**

  We’re taking a closer look at how SMASH was able to spread the word about its cause and reach key influencers, in an effort to raise \$500,000 to provide students of color with access to college and career resources. This case study highlights how Audiense helped SMASH to utilize X data to reach the most relevant audiences for this cause.
</Note>

## Situation

Following a wave of social justice activism in the summer of 2020, SMASH – a nonprofit organization dedicated to helping provide students of color access to college and career readiness resources – saw the opportunity to ramp up fundraising and spread the word about its cause.

SMASH created #SMASHmatch, a six-week campaign during June - July 2020 with the goal to raise \$500,000 through a 1:1 match from a SMASH donor.

The goals of the organization’s social media push and #SMASHmatch campaign were two-fold:

1. Build greater awareness of SMASH and how the organization is looking to develop the next generation of socially conscious STEM leaders, providing corporate donors a meaningful cause to support in the fight against systemic racism.

2. Raise money from new and existing SMASH donors.

With such a large goal, SMASH acknowledged that they’d need to take a direct approach to outreach.

SMASH turned to Audiense, whose X Marketing product specializes in delivering impactful X campaigns thanks to its powerful audience targeting, to determine who their best outreach candidates were and how many potential donors were fair game based on their existing X followers.

Rather than SMASH combing through their follower list by hand, Audiense did the heavy lifting. Their platform made it easy to sort X followers based on their reach, follower count, and other parameters relevant to the campaign.

## Solution

SMASH took a three-point approach to raise funds and build awareness:

1. Use X to promote the campaign and reach out to specific influencers for donations.
2. Promote the \$500,000 donor match to inspire existing donors to renew their gift.
3. Motivate corporate donors to partner with SMASH to double their impact throughout the campaign.

Below are the steps SMASH took and how they used Audiense’s analytics platform to build their fundraising campaign.

1. **Identify their engaged, verified social media influencers**

   Thanks to Audiense, SMASH streamlined its campaign by knowing exactly who its most engaged followers were and which ones had the most reach via X verification. These would become prime outreach candidates not only for securing donations but also for spreading the word through Retweets.

   <img alt="" />

2. **Engage with their target audience directly and track results**

   With Audiense’s data, SMASH was able to confidently approach its outreach candidates through Direct Tweets that requested donations and Retweets.

   They managed to secure a $10,000 donation during the first day and received a staggering $500,000 donation to meet their original funder goal by day three. The campaign continued to rack up donations and Retweets with no signs of slowing down.

3. **Keep the momentum going by identifying new donors to target**

   Using Audiense, the organization managed to explore relevant outreach candidates beyond their own followers and immediate network. The fresh outreach resulted in more verified Retweets and support for the campaign which came from athletes, actors, entertainers, political commentators, and other celebrities

## Impact

SMASH and Audiense’s efforts resulted in achievements far beyond their initial goals:

* The campaign raised more than \$1M during its six-week run.
* SMASH garnered over 20 million X impressions and 1,100 new followers (including some of the verified influencers that interacted with the campaign.
* Interactions with over 1,000 influencers.
* Shout-outs and Retweets from NFL and NBA players including Ezekiel Elliott, Alshon Jeffery, Baron Davis, and Isaiah Thomas.

When done effectively, audience targeting on X can help companies reach people – and goals – they otherwise thought wouldn’t be possible.

<img alt="" />


# Typefully x Raycast
Source: https://docs.x.com/success-stories/typefully

How Typefully and Raycast use the X API to help creators and companies draft, schedule, and optimize Posts and threads from a streamlined workflow.

[Typefully](https://typefully.com/) is very popular among creators, agencies, and teams for its minimal yet powerful interface, with more than 200k registered users. Among social media scheduling app, it’s the one that offers the simplest and most complete publishing and scheduling experience for X, and also the one with the best high-fidelity preview of how the content looks after publishing.

## The Challenge

Typefully was born a tool to write threads on Twitter, before it was rebranded as X. As users of the X API for many years now, they’ve always followed and updated X API developments closely to provide the best possible experience to their users, and adopt the latest features very quickly. By having a close relationship with X, Typefully has been able to support new X features quickly and offer a very complete publishing experience to their users.

## The Solution

[Typefully](https://typefully.com/) leverages several key features of the X API to power their core functionality, ensuring seamless publishing, analytics, and scheduling for their users.

For **post publishing and scheduling**, we rely on POST /2/tweets to support all post types—text, media, polls, and long-form posts—along with advanced thread management, auto-retries, and quote tweet handling. Typefully’s scheduling system integrates deeply with X, enabling timezone-aware posting, queue management, and automation features like auto-retweets and follow-ups.

**Analytics** is another key pillar, utilizing GET /2/tweets to provide real-time engagement tracking, historical data imports, and insights such as impressions, engagement rates, and link clicks. This data — 1M+ posts processed per month — feeds into their advanced analytics tools, helping users optimize their content strategy.

On the account management side, OAuth 2.0 and real-time verification ensure seamless multi-account support, with robust rate limit handling and token refresh mechanisms.

It’s exciting, as Typefully is a small team of just 5 people, to empower creators and companies via the X API to publish more than 130,000 posts every month.

<img alt="Newtypefully1 Pn" />

## The Results

*Typefully*'s tight integration with the X API has made a real difference in how their users publish and manage their content — making Typefully one of the most dependable X publishing tools available. Their users particularly value the high-fidelity preview that accurately shows how content will appear after publishing, eliminating surprises after publishing.

[**<u>A prime example is the Raycast whose team uses Typefully to manage multiple X accounts</u>**](https://www.raycast.com/)  - both their company profile and team members' personal accounts.

Their social media workflow is streamlined through our **collaboration features**, allowing team members to **share draft posts, leave feedback comments, and organize them with tags.** This coordinated approach has been particularly valuable for perfectly timing announcements and news about Raycast products and features.

<img alt="Newtypefully2(1) Pn" />

The collaboration tools have eliminated communication silos for teams like Raycast, **reducing the time spent on social media management while improving content quality through close feedback loops**.

By leveraging the X API through Typefully, companies maintain a consistent and engaging social presence without the complexity typically associated with multi-account management. Teams can focus on creating quality content rather than dealing with publishing logistics, resulting in more effective communication on X.


# Developer Support
Source: https://docs.x.com/support

Find support channels for the X API, including the developer community forum, Stack Overflow, GitHub issues, status page, and contact options.

Whether you're troubleshooting an issue, looking for guidance, or want to connect with other developers, we've got you covered.

***

## Community and help

<CardGroup>
  <Card title="Developer Forums" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=ce6313d8c0b7b4e5363f2ce80b89f7e4" href="https://devcommunity.x.com">
    Ask questions, share your projects, and get help from the X developer community and team. This is the best place to get support for technical questions.
  </Card>

  <Card title="API Status" icon="signal" href="https://developer.x.com/status">
    Check the current operational status of X API v2, Enterprise APIs, and the Developer Console.
  </Card>
</CardGroup>

***

## Contact and forms

<CardGroup>
  <Card title="Enterprise API Interest" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bank.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=6dd9ad48fa88936abb112b49e022abff" href="/forms/enterprise-api-interest">
    Interested in enterprise-level API access? Submit your interest and our team will reach out.
  </Card>

  <Card title="Billing Support" icon="credit-card" href="/forms/billing-support">
    Get help with billing questions for Self-serve and Enterprise API subscriptions.
  </Card>

  <Card title="Policy Support" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-check.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=768533bde161ac68862de87449f011c3" href="https://help.x.com/forms/platform">
    Questions about policies, compliance, or need approval for specific use cases? Contact our policy team.
  </Card>
</CardGroup>

***

## Documentation and resources

<CardGroup>
  <Card title="Getting Started" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/getting-started/make-your-first-request">
    New to the X API? Start here to get your API keys and make your first request.
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/introduction">
    Complete reference for all X API v2 endpoints, parameters, and response formats.
  </Card>

  <Card title="Authentication Guide" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/fundamentals/authentication/overview">
    Learn about OAuth 1.0a, OAuth 2.0, and how to authenticate your API requests.
  </Card>

  <Card title="SDKs & Libraries" icon="cube" href="/tools-and-libraries">
    Official Python and TypeScript SDKs to speed up your development.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/x-api/fundamentals/rate-limits">
    Understand rate limits and how to handle them in your application.
  </Card>

  <Card title="Error Codes" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-info-circle.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=8ec54c5126797535385f8241158b81ca" href="/x-api/fundamentals/response-codes-and-errors">
    Reference for API error codes and how to resolve common issues.
  </Card>
</CardGroup>

***

## Policies and guidelines

<CardGroup>
  <Card title="Developer Guidelines" icon="scale-balanced" href="/developer-guidelines">
    Practical guide to what's allowed and what's not when building with the X API.
  </Card>

  <Card title="Developer Agreement" icon="file-contract" href="/developer-terms/agreement">
    The binding legal terms for X API access.
  </Card>

  <Card title="Developer Policy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-check.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=768533bde161ac68862de87449f011c3" href="/developer-terms/policy">
    Rules and expectations for building on X.
  </Card>

  <Card title="Restricted Use Cases" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-block.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=702a65b4001948aebcc42635b8e2eac7" href="/developer-terms/restricted-use-cases">
    Activities that are prohibited or require special approval.
  </Card>
</CardGroup>

***

## Troubleshooting tips

<AccordionGroup>
  <Accordion title="I'm getting 401 Unauthorized errors" icon="lock">
    * Double-check your API keys and tokens are correct
    * Ensure you're using the right authentication method for the endpoint (OAuth 1.0a vs OAuth 2.0)
    * Verify your app has the required permissions (read, write, DM access)
    * Check that your tokens haven't expired—regenerate if needed
  </Accordion>

  <Accordion title="I'm hitting rate limits" icon="gauge">
    * Check the `x-rate-limit-*` headers in API responses to monitor your usage
    * Implement exponential backoff when you receive 429 errors
    * Cache responses where possible to reduce API calls
    * Consider upgrading your access tier for higher limits
    * See the [Rate Limits guide](/x-api/fundamentals/rate-limits) for detailed information
  </Accordion>

  <Accordion title="My app was suspended" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-block.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=702a65b4001948aebcc42635b8e2eac7">
    * Review the [Developer Guidelines](/developer-guidelines) to understand what may have caused the suspension
    * Check your email for any communication from X about the suspension
    * Submit an appeal through the [Policy Support form](https://help.x.com/forms/platform)
    * Common causes: automated likes, unsolicited DMs/mentions, scraping, rate limit abuse
  </Accordion>

  <Accordion title="I need higher API access or limits" icon="arrow-up">
    * Review the [pricing tiers](/x-api/getting-started/pricing) to find the right plan
    * For enterprise needs, submit the [Enterprise API Interest form](/forms/enterprise-api-interest)
    * For access upgrades, use the [Use Case Upgrade form](/forms/use-case/upgrade)
  </Accordion>

  <Accordion title="I can't find the endpoint I need" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834">
    * Browse the full [API Reference](/x-api/introduction)
    * Check if the functionality exists in [v1.1 endpoints](/x-api/migrate/overview) that may not be in v2 yet
    * Ask in the [Developer Forums](https://devcommunity.x.com) if you're unsure
  </Accordion>
</AccordionGroup>

***

## Stay updated

<CardGroup>
  <Card title="Changelog" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-history.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=6afe17587c08ee621e37afde19a07ff1" href="/changelog">
    Latest API updates, new features, and changes.
  </Card>

  <Card title="@XDevelopers" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-logo-x.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=53e3153f3b8d6efdad31484ef133b274" href="https://x.com/XDevelopers">
    Follow for announcements and developer news.
  </Card>

  <Card title="Incidents" icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" href="/incidents">
    History of past incidents and their resolutions.
  </Card>
</CardGroup>


# Tools & Libraries
Source: https://docs.x.com/tools-and-libraries

Official X API SDKs in Python and TypeScript, CLI tools like xurl, the playground server, MCP servers for AI, and community client libraries.

Speed up your development with official SDKs, developer tools, and community libraries.

***

## Official SDKs

<CardGroup>
  <Card title="Python SDK" icon="python" href="/xdks/python/overview">
    Async support, type hints, and automatic token refresh. Perfect for data analysis and automation.
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/xdks/typescript/overview">
    Full type safety and ESM support. Works in Node.js and modern bundlers.
  </Card>
</CardGroup>

### Quick start

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install xdk
    ```

    ```python theme={null}
    from xdk import Client

    client = Client(bearer_token="YOUR_BEARER_TOKEN")

    for page in client.posts.search_recent(query="api", max_results=10):
        if page.data and len(page.data) > 0:
            print(page.data[0].text)
            break
    ```

    <Button href="/xdks/python/overview">Full Python guide</Button>
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install @xdevplatform/xdk
    ```

    ```typescript theme={null}
    import { Client } from '@xdevplatform/xdk';

    const client = new Client({ bearerToken: 'YOUR_BEARER_TOKEN' });
    const userResponse = await client.users.getByUsername('XDevelopers');
    console.log(userResponse.data?.username);
    ```

    <Button href="/xdks/typescript/overview">Full TypeScript guide</Button>
  </Tab>
</Tabs>

***

## Developer tools

<CardGroup>
  <Card title="Postman Collection" icon="server" href="https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80">
    Interactive API testing for all v2 endpoints.
  </Card>

  <Card title="xurl" icon="terminal" href="/tools/xurl">
    curl-like CLI for the X API with built-in OAuth authentication. No manual token management.
  </Card>

  <Card title="API Playground" icon="flask" href="https://github.com/xdevplatform/playground">
    Local mock server for testing X API v2 endpoints without using real credits.
  </Card>

  <Card title="Agent Resources" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-ai-agents.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=53171c3a2a9432187cf705d13e24651b" href="/tools/ai">
    XMCP, llms.txt, skill.md, docs MCP server, and resources for AI-powered development.
  </Card>
</CardGroup>

### Other tools

| Tool                                                    | Description                                                 |
| :------------------------------------------------------ | :---------------------------------------------------------- |
| [OpenAPI Spec](https://api.x.com/2/openapi.json)        | Machine-readable API specification                          |
| [twitter-text](https://github.com/twitter/twitter-text) | Parse and validate post text, count characters              |
| [Embed Generator](https://publish.x.com/#)              | Build embeddable posts, timelines, or buttons for your site |

***

## Community libraries

Community-maintained libraries with X API v2 support. Check each library's documentation for current coverage.

<Tabs>
  <Tab title="Python">
    | Library                                                      | Description                            |
    | :----------------------------------------------------------- | :------------------------------------- |
    | [tweepy](https://github.com/tweepy/tweepy)                   | Popular Python library with v2 support |
    | [twarc](https://twarc-project.readthedocs.io/)               | CLI and library for data collection    |
    | [python-twitter](https://github.com/sns-sdks/python-twitter) | Simple Python wrapper                  |
    | [TwitterAPI](https://github.com/geduldig/TwitterAPI)         | Minimal Python wrapper                 |
  </Tab>

  <Tab title="JavaScript/TypeScript">
    | Library                                                              | Description                                  |
    | :------------------------------------------------------------------- | :------------------------------------------- |
    | [node-twitter-api-v2](https://github.com/PLhery/node-twitter-api-v2) | Strongly-typed, full-featured Node.js client |
    | [twitter.js](https://github.com/twitterjs/twitter.js)                | Object-oriented Node.js library              |
    | [twitter-v2](https://github.com/HunterLarco/twitter-v2)              | Async client library                         |
  </Tab>

  <Tab title="Go">
    | Library                                                         | Description             |
    | :-------------------------------------------------------------- | :---------------------- |
    | [go-twitter](https://github.com/g8rswimmer/go-twitter)          | Go library for v2 API   |
    | [gotwi](https://github.com/michimani/gotwi)                     | Go wrapper for v2       |
    | [twitter-stream](https://github.com/Fallenstedt/twitter-stream) | Filtered stream wrapper |
  </Tab>

  <Tab title="Java/Kotlin">
    | Library                                               | Description            |
    | :---------------------------------------------------- | :--------------------- |
    | [twittered](https://github.com/redouane59/twittered)  | Java client for v2     |
    | [twitter4j-v2](https://github.com/takke/twitter4j-v2) | Twitter4J v2 wrapper   |
    | [KTweet](https://github.com/ChromasIV/KTweet)         | Kotlin v2 library      |
    | [Tweedle](https://github.com/tyczj/Tweedle)           | Kotlin Android library |
  </Tab>

  <Tab title="PHP">
    | Library                                                           | Description           |
    | :---------------------------------------------------------------- | :-------------------- |
    | [twitter-api-v2-php](https://github.com/noweh/twitter-api-v2-php) | PHP v2 client         |
    | [bird-elephant](https://github.com/danieldevine/bird-elephant)    | PHP v2 library        |
    | [twitteroauth](https://github.com/abraham/twitteroauth)           | Popular OAuth library |
  </Tab>

  <Tab title="Ruby">
    | Library                                                           | Description       |
    | :---------------------------------------------------------------- | :---------------- |
    | [tweetkit](https://github.com/julianfssen/tweetkit)               | Ruby v2 client    |
    | [twitter\_oauth2](https://github.com/nov/twitter_oauth2)          | OAuth 2.0 library |
    | [omniauth-twitter2](https://github.com/unasuke/omniauth-twitter2) | OmniAuth strategy |
  </Tab>

  <Tab title="Other">
    | Language       | Library                                                                                                    |
    | :------------- | :--------------------------------------------------------------------------------------------------------- |
    | **C#/.NET**    | [Tweetinvi](https://github.com/linvi/tweetinvi), [LinqToTwitter](https://github.com/JoeMayo/LinqToTwitter) |
    | **Rust**       | [twitter-v2](https://github.com/jpopesculian/twitter-v2-rs)                                                |
    | **Swift**      | [Twift](https://github.com/daneden/Twift/), [TwitterAPIKit](https://github.com/mironal/TwitterAPIKit)      |
    | **R**          | [academictwitteR](https://github.com/cjbarrie/academictwitteR)                                             |
    | **PowerShell** | [BluebirdPS](https://github.com/thedavecarroll/BluebirdPS)                                                 |
  </Tab>
</Tabs>

<Note>
  Community libraries are not maintained by X. Check their repositories for support and current status.
</Note>

***

## Code samples

* [X API v2 Sample Code](https://github.com/xdevplatform/Twitter-API-v2-sample-code) — Examples in Python, JavaScript, Ruby, and more
* [Code Samples Repo](https://github.com/xdevplatform/samples) — Examples using the official XDKs
* [X Developer GitHub](https://github.com/xdevplatform) — Official repos and tools

***

## X Ads API libraries

For tools and libraries specific to the X Ads API, see the [Ads API tools and libraries](/x-ads-api/tools-and-libraries) page.


# Agent Resources
Source: https://docs.x.com/tools/ai

Resources for AI agents using the X API, including llms.txt, skill.md, MCP servers, OpenAPI specs, and integration guides for Grok, Cursor, and Windsurf.

Resources for connecting AI tools to the X API and its documentation.

***

## Use the X API from AI tools

Give your AI agent the ability to call X API endpoints directly.

**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](https://api.x.com/2/openapi.json)) for auto-generating clients or feeding into agents.

| Resource         | What it does                                                                     | URL                                                          |
| :--------------- | :------------------------------------------------------------------------------- | :----------------------------------------------------------- |
| **X MCP**        | Hosted MCP server — agents can search, look up users, manage bookmarks, and more | [docs.x.com/tools/mcp](/tools/mcp)                           |
| **OpenAPI Spec** | Machine-readable API definition for code generation and agent tooling            | [api.x.com/2/openapi.json](https://api.x.com/2/openapi.json) |

***

## Read X API docs from AI tools

Give your AI agent context on how the X API works.

**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                                                          |
| :---------------- | :----------------------------------------------------------- | :----------------------------------------------------------- |
| **llms.txt**      | Documentation index — page titles, URLs, and descriptions    | [docs.x.com/llms.txt](https://docs.x.com/llms.txt)           |
| **llms-full.txt** | Complete docs in a single file for full-context loading      | [docs.x.com/llms-full.txt](https://docs.x.com/llms-full.txt) |
| **skill.md**      | Capability summary — actions, inputs, and constraints        | [docs.x.com/skill.md](https://docs.x.com/skill.md)           |
| **Docs MCP**      | MCP server — agents can search and read doc pages on the fly | [docs.x.com/mcp](https://docs.x.com/mcp)                     |


# llms.txt & llms-full.txt
Source: https://docs.x.com/tools/llms-txt

Use llms.txt and llms-full.txt to give AI tools like Cursor, Windsurf, and Grok structured access to X API documentation for accurate code generation.

**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)                                                                                                     | 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 (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
* **Cursor / Windsurf**: Add `https://docs.x.com/llms-full.txt` as documentation context for your project
* **Custom agents**: Fetch the file programmatically and include it in your system prompt or context window

```bash theme={null}
# Fetch the documentation index
curl https://docs.x.com/llms.txt

# Fetch the complete documentation
curl https://docs.x.com/llms-full.txt

# Fetch any individual page as Markdown
curl https://docs.x.com/tools/llms-txt.md
```


# MCP servers for the X API and X developer docs
Source: https://docs.x.com/tools/mcp

Connect Grok, Cursor, and other AI tools to the X API and X developer docs through hosted Model Context Protocol servers using xurl and docs search.

Two [MCP](https://modelcontextprotocol.io) (Model Context Protocol) servers are available for working with X from AI tools:

| Server       | What it does                                                                                    | URL                                                      |
| :----------- | :---------------------------------------------------------------------------------------------- | :------------------------------------------------------- |
| **X MCP**    | Call X API endpoints (search posts, look up users, bookmarks, trends, news, Articles, and more) | `https://api.x.com/mcp` (hosted; connect via `xurl mcp`) |
| **Docs MCP** | Search and read X API documentation                                                             | `https://docs.x.com/mcp` (hosted)                        |

***

## X MCP — X API

Connect any MCP-compatible AI tool (Grok Build, Cursor, Claude, VS Code, and others) directly to the **X API**. The model can then search the full archive, look up users, manage bookmarks, fetch trends and news, and draft Articles — all with your own X account's permissions.

The X API exposes a hosted **Streamable HTTP** MCP server at **`https://api.x.com/mcp`** (protocol `2025-06-18`, `serverInfo: xmcp`). You reach it through the open-source **`xurl mcp`** bridge, which handles OAuth for you and injects a fresh Bearer token on every call.

### Capabilities at a glance

| Category          | What the model can do                                                                         |
| ----------------- | --------------------------------------------------------------------------------------------- |
| **Posts**         | Fetch posts, see likers / reposters / quoters, recent counts                                  |
| **Search**        | Full-archive post search, user search, news search                                            |
| **Users**         | Resolve the current user, look up by id / handle, read a user's posts, timeline, and mentions |
| **Bookmarks**     | List / add / remove bookmarks and manage bookmark folders                                     |
| **News & Trends** | Get news stories, get trends for a location (WOEID)                                           |
| **Articles**      | Create draft Articles and publish them                                                        |

### How it works

X's OAuth requires *your own* developer app. There is no dynamic client registration, and `api.x.com/mcp` does not advertise native MCP OAuth discovery. Instead of pointing your client at the URL directly, you run a tiny local bridge. The bridge owns the app identity, performs the one-time login, and keeps the token fresh.

```mermaid theme={null}
flowchart LR
    A["MCP client<br/>(Grok Build, Cursor, …)"] -- "stdio JSON-RPC" --> B["xurl mcp<br/>(local bridge)"]
    B -- "HTTPS + Authorization: Bearer" --> C[("api.x.com/mcp")]
    B <-- "OAuth2 PKCE login + auto-refresh" --> D["X OAuth"]
```

* The bridge runs via the **npm launcher** (`npx`), so there is **no separate install step**.
* On **first run with no cached token**, it opens your browser for a one-time OAuth2 login, then caches and **auto-refreshes** the token forever after.
* All diagnostics go to **stderr**; **stdout stays a clean JSON-RPC channel**.

### Getting started

Pick one of two routes:

* **Simple — App-only Bearer.** Paste your app's Bearer token into an `Authorization` header on the MCP client. No bridge, no browser login. Read-only endpoints; no user context (can't act as you). Works with clients that support remote MCP with custom headers.
* **Full — `xurl mcp` bridge (OAuth 2.0 user context).** A local bridge handles the OAuth 2.0 PKCE login and auto-refreshes tokens, so the model acts with your account's scopes. Required for writes (bookmarks, Articles) and any user-context tool.

#### Simple route (app-only Bearer)

1. **Create an X app** in the [X Developer Portal](https://developer.x.com).
2. **Copy your App-only Bearer token** from the app's "Keys and tokens" page.
3. Point your client at `https://api.x.com/mcp` with the token as an `Authorization` header — see [App-only (direct URL, no bridge)](#app-only-direct-url-no-bridge) below for the snippet.

#### Full route (xurl bridge)

1. **Create an X app** with **OAuth 2.0** enabled.
2. **Register the redirect URI** `http://localhost:8080/callback` on the app (required for the first-run browser login). To use a different one, set `REDIRECT_URI` and register that instead.
3. **Copy your `CLIENT_ID` and `CLIENT_SECRET`** — you'll put them in the client config. If you ever run `xurl auth oauth2` manually (e.g., the headless flow below), export them as environment variables in that shell first — the login fails in the browser without them.
4. **Have Node.js installed** (for `npx`).
5. We recommend you **install [xurl](https://github.com/xdevplatform/xurl)**:

   ```bash theme={null}
   brew install --cask xdevplatform/tap/xurl      # Homebrew
   npm install -g @xdevplatform/xurl              # npm (global)
   curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash
   ```

<Note>
  **First login needs a browser.** On a headless/remote box, authenticate out-of-band first with `xurl auth oauth2 --headless` (paste-a-code flow), then the bridge just reuses the cached token. See [Headless](/tools/mcp#headless--remote-machines).
</Note>

### Connect your client

#### 1. Grok Build

<CodeGroup>
  ```toml xurl bridge (~/.grok/config.toml) theme={null}
  [mcp_servers.xapi]
  command = "npx"
  args = ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"]
  enabled = true
  startup_timeout_sec = 300          # give the first-run browser login time

  [mcp_servers.xapi.env]
  CLIENT_ID = "YOUR_X_APP_CLIENT_ID"
  CLIENT_SECRET = "YOUR_X_APP_CLIENT_SECRET"
  ```

  ```toml App-only Bearer (~/.grok/config.toml) theme={null}
  [mcp_servers.xapi]
  url = "https://api.x.com/mcp"
  enabled = true

  [mcp_servers.xapi.headers]
  Authorization = "Bearer YOUR_APP_ONLY_BEARER_TOKEN"
  ```
</CodeGroup>

Or add the xurl bridge with one command (the `-e` flags become the server's environment, args after `--` go to `npx`):

```bash theme={null}
grok mcp add xapi npx \
  -e CLIENT_ID=YOUR_X_APP_CLIENT_ID \
  -e CLIENT_SECRET=YOUR_X_APP_CLIENT_SECRET \
  -- -y @xdevplatform/xurl mcp https://api.x.com/mcp
```

Verify and list:

```bash theme={null}
grok mcp doctor xapi      # ✓ server started, ✓ handshake OK, ✓ tools discovered
grok mcp list
```

The first time a tool is invoked (or on `doctor`), your browser opens for the X login — complete it once and you're set.

#### 2. Cursor

Create `~/.cursor/mcp.json` (global, all projects) or `.cursor/mcp.json` (this project only):

<CodeGroup>
  ```json title="xurl bridge" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
  {
    "mcpServers": {
      "xapi": {
        "command": "npx",
        "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
        "env": {
          "CLIENT_ID": "YOUR_X_APP_CLIENT_ID",
          "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET"
        }
      }
    }
  }
  ```

  ```json App-only Bearer theme={null}
  {
    "mcpServers": {
      "xapi": {
        "url": "https://api.x.com/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_APP_ONLY_BEARER_TOKEN"
        }
      }
    }
  }
  ```
</CodeGroup>

Then open **Cursor → Settings → MCP**, confirm **xapi** shows a green dot and its tools. On first use Cursor spawns the bridge and your browser opens for login; the tool list populates once the handshake completes.

#### 3. Claude Desktop

Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):

<CodeGroup>
  ```json xurl bridge theme={null}
  {
    "mcpServers": {
      "xapi": {
        "command": "npx",
        "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
        "env": { "CLIENT_ID": "YOUR_X_APP_CLIENT_ID", "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET" }
      }
    }
  }
  ```

  ```json App-only Bearer theme={null}
  {
    "mcpServers": {
      "xapi": {
        "url": "https://api.x.com/mcp",
        "headers": { "Authorization": "Bearer YOUR_APP_ONLY_BEARER_TOKEN" }
      }
    }
  }
  ```
</CodeGroup>

Restart Claude Desktop; the X tools appear in the tools (🔌) menu.

#### 4. VS Code (GitHub Copilot / Agent mode)

Add to `.vscode/mcp.json`:

<CodeGroup>
  ```json xurl bridge theme={null}
  {
    "servers": {
      "xapi": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
        "env": { "CLIENT_ID": "YOUR_X_APP_CLIENT_ID", "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET" }
      }
    }
  }
  ```

  ```json App-only Bearer theme={null}
  {
    "servers": {
      "xapi": {
        "type": "http",
        "url": "https://api.x.com/mcp",
        "headers": { "Authorization": "Bearer YOUR_APP_ONLY_BEARER_TOKEN" }
      }
    }
  }
  ```
</CodeGroup>

#### 5. Any MCP client

**xurl bridge (stdio):**

| Field           | Value                                                          |
| --------------- | -------------------------------------------------------------- |
| `command`       | `npx`                                                          |
| `args`          | `["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"]` |
| `env`           | `CLIENT_ID`, `CLIENT_SECRET`                                   |
| startup timeout | **≥ 300s** (so the first-run login can finish)                 |

If you installed `xurl` natively, replace `command`/`args` with `"command": "xurl", "args": ["mcp", "https://api.x.com/mcp"]`.

**App-only Bearer (remote HTTP):**

| Field                   | Value                               |
| ----------------------- | ----------------------------------- |
| `url`                   | `https://api.x.com/mcp`             |
| `headers.Authorization` | `Bearer YOUR_APP_ONLY_BEARER_TOKEN` |

### Authentication

#### OAuth 2.0 user context (default)

The bridge authenticates as **you** (PKCE flow), so tools act with your account's scopes. Resolution order for credentials: **`CLIENT_ID`/`CLIENT_SECRET` env vars → the active app in `~/.xurl`**. The bridge caches tokens in `~/.xurl` and refreshes them automatically (including a forced refresh after a `401`).

#### First-run browser login

With no cached token, the bridge prints to stderr and opens your browser:

```json theme={null}
[xurl mcp] no valid OAuth2 token; opening the browser to sign in -- complete the login to start the bridge...
[xurl mcp] authentication complete; starting bridge
```

The MCP handshake is held until you finish — that's why clients need a generous `startup_timeout_sec`.

#### Headless / remote machines

No reachable browser? Authenticate once out-of-band, then start the client:

```bash theme={null}
# Required: the env block in your client config only applies to the bridge,
# not to manual xurl runs — export the credentials in this shell first.
export CLIENT_ID="YOUR_X_APP_CLIENT_ID"
export CLIENT_SECRET="YOUR_X_APP_CLIENT_SECRET"

xurl auth oauth2 --headless                 # prints an auth URL; you paste back the redirect URL/code
xurl auth oauth2 --app my-app --headless    # for a specific app
```

#### App-only (direct URL, no bridge)

For read endpoints, you can skip the bridge and point a client straight at the URL with a **static App-only Bearer token**. This is useful for clients that support remote MCP with custom headers:

```toml theme={null}
# ~/.grok/config.toml
[mcp_servers.xapi_direct]
url = "https://api.x.com/mcp"
enabled = true

[mcp_servers.xapi_direct.headers]
Authorization = "Bearer YOUR_APP_ONLY_BEARER_TOKEN"
```

Trade-off: no auto-refresh and no user context (no actions as you). The bridge is recommended for full functionality.

#### Multiple apps & accounts

<Note>
  The OAuth login authorizes **whichever X account is logged in when the browser opens** — not necessarily the account that owns the app. If you're posting on behalf of a secondary/bot account, switch to that account in your browser before completing the login (or use `-u` to pick a previously authorized user).
</Note>

```bash theme={null}
xurl --app my-app mcp                  # bridge using a specific registered app
xurl mcp -u alice https://api.x.com/mcp  # act as a specific OAuth2 user
```

In a client config, add `"--app", "my-app"` or `"-u", "alice"` to `args`.

### Configuration reference

| Setting                       | Where         | Notes                                                                                           |
| ----------------------------- | ------------- | ----------------------------------------------------------------------------------------------- |
| `CLIENT_ID` / `CLIENT_SECRET` | `env`         | Your X app credentials (or rely on a registered app in `~/.xurl`)                               |
| `REDIRECT_URI`                | `env`         | Overrides the callback; must be registered on the app. Default `http://localhost:8080/callback` |
| `startup_timeout_sec`         | client config | Set **≥ 300** so first-run login can complete                                                   |
| `[URL]` positional            | `args`        | Defaults to `https://api.x.com/mcp`                                                             |
| `--app NAME`                  | `args`        | Use a specific registered app                                                                   |
| `-u, --username`              | `args`        | Act as a specific OAuth2 user                                                                   |

Advanced env overrides (rarely needed): `AUTH_URL`, `TOKEN_URL`, `API_BASE_URL`, `INFO_URL`.

### Verify & troubleshoot

```bash theme={null}
grok mcp doctor xapi          # Grok Build: end-to-end check
# or test the bridge by hand (Ctrl-C to exit):
npx -y @xdevplatform/xurl mcp https://api.x.com/mcp
```

| Symptom                                                                           | Cause / Fix                                                                                                                                                             |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client times out on startup                                                       | Raise `startup_timeout_sec` to 300+; the bridge is waiting on your browser login                                                                                        |
| Browser never opens                                                               | No display (headless) → run `xurl auth oauth2 --headless` first; ensure `npx` resolves                                                                                  |
| `401` / `token refresh failed`                                                    | App credentials wrong, or refresh token revoked → re-run the login (`xurl auth oauth2 [--app NAME]`)                                                                    |
| Browser shows "Something went wrong — You weren't able to give access to the App" | `CLIENT_ID`/`CLIENT_SECRET` not set where `xurl` runs → put them in the client's `env` block, or `export` them in your shell before running `xurl auth oauth2` manually |
| Redirect/callback error in browser                                                | `http://localhost:8080/callback` not registered on the app (or `REDIRECT_URI` mismatch)                                                                                 |
| `client-not-enrolled` after login                                                 | App isn't in the right X package/environment → in the portal move it to **Pay-per-use** + **Production**                                                                |
| `npx` pulls a stale version                                                       | A private registry mirror is default → pin `--registry=https://registry.npmjs.org/` in `args`                                                                           |
| Empty/garbled tool output                                                         | Don't run the client with `--verbose`; stdout must stay a clean JSON-RPC channel                                                                                        |

### Security & best practices

* **Treat `~/.xurl` and access tokens as secrets** — don't paste them into chats, logs, or shared configs. Prefer per-project `.mcp.json`/`.grok/config.toml` that reference env vars over committing raw secrets.
* **Use a dedicated app** for MCP with only the scopes you need.
* **Writes count against rate limits** (bookmarks, `article_publish`) and are stricter than reads; expect occasional `429`s and back off.
* **The bridge is local** — your credentials never leave your machine except as a Bearer token sent over TLS to `api.x.com`.

***

## Docs MCP — documentation search

X hosts an MCP server for the X API documentation at `https://docs.x.com/mcp`. Connect it to your AI tool to search and read documentation pages without leaving your workflow.

### Available tools

| Tool         | Description                                                                                           |
| :----------- | :---------------------------------------------------------------------------------------------------- |
| `search_x`   | Search across the X documentation for relevant information, code examples, API references, and guides |
| `get_page_x` | Retrieve the full content of a specific documentation page by its path                                |

### Configuration

Add the docs MCP server to your MCP client configuration:

```json theme={null}
{
  "mcpServers": {
    "x-docs": {
      "url": "https://docs.x.com/mcp"
    }
  }
}
```

This is useful when you're building with the X API and want your AI assistant to look up endpoint details, authentication guides, or code examples on the fly.

***

## Using both servers together

You can connect both MCP servers simultaneously. This gives your AI assistant the ability to both look up documentation *and* call the API.

**Grok Build** (`~/.grok/config.toml`):

```toml title="Example" lines wrap icon="file-lines" theme={null}
[mcp_servers.xapi]
command = "npx"
args = ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"]
enabled = true
startup_timeout_sec = 300

[mcp_servers.xapi.env]
CLIENT_ID = "YOUR_X_APP_CLIENT_ID"
CLIENT_SECRET = "YOUR_X_APP_CLIENT_SECRET"

[mcp_servers.x-docs]
url = "https://docs.x.com/mcp"
enabled = true
```

**Cursor / Claude-style** (`mcp.json`):

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "mcpServers": {
    "xapi": {
      "command": "npx",
      "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
      "env": {
        "CLIENT_ID": "YOUR_X_APP_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET"
      }
    },
    "x-docs": {
      "url": "https://docs.x.com/mcp"
    }
  }
}
```

***

## OpenAPI specification

The machine-readable API specification for all X API v2 endpoints.

| Resource                | URL                                                                    |
| :---------------------- | :--------------------------------------------------------------------- |
| **OpenAPI Spec (JSON)** | [`https://api.x.com/2/openapi.json`](https://api.x.com/2/openapi.json) |

```bash theme={null}
curl https://api.x.com/2/openapi.json -o openapi.json
```

You can use it to auto-generate API clients, import into [Postman](https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80), feed into custom AI agents, or validate request/response schemas.


# API Playground
Source: https://docs.x.com/tools/playground

Run a local mock server to test X API v2 endpoints during development without consuming API credits, plus example requests and response payloads.

The [API Playground](https://github.com/xdevplatform/playground) is a local mock server that simulates the full X API v2. Test endpoints, build prototypes, and explore the API without consuming real API credits.

<Card title="GitHub repository" icon="github" href="https://github.com/xdevplatform/playground">
  Source code, releases, and full documentation.
</Card>

***

## Features

<CardGroup>
  <Card title="Full API v2 compatibility" icon="check">
    All endpoints supported with request validation via OpenAPI specs and realistic error responses.
  </Card>

  <Card title="Interactive web UI" icon="browser">
    Visual endpoint explorer at `http://localhost:8080/playground` for testing in the browser.
  </Card>

  <Card title="No credits needed" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-coins.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=d8b17de3fb4032d86b77606ea95fcb55">
    Everything runs locally with mock data — no API keys or billing required.
  </Card>

  <Card title="Stateful operations" icon="database">
    In-memory state with optional file persistence. Create posts, then look them up.
  </Card>
</CardGroup>

***

## Installation

Requires Go 1.21+. Install from source or download a pre-built binary from [releases](https://github.com/xdevplatform/playground/releases).

<Tabs>
  <Tab title="Go install">
    ```bash theme={null}
    go install github.com/xdevplatform/playground/cmd/playground@latest
    playground start
    ```
  </Tab>

  <Tab title="Build from source">
    ```bash theme={null}
    git clone https://github.com/xdevplatform/playground.git
    cd playground
    go build -o playground ./cmd/playground
    ./playground start
    ```
  </Tab>
</Tabs>

The server starts at `http://localhost:8080` by default.

***

## Quick start

Make requests just like you would to the real API — use `test_token` as your bearer token:

```bash title="me" lines wrap icon="terminal" theme={null}
# Look up a user
curl -H "Authorization: Bearer test_token" \
  http://localhost:8080/2/users/me

# Create a post
curl -X POST -H "Authorization: Bearer test_token" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from the playground!"}' \
  http://localhost:8080/2/tweets

# Search posts
curl -H "Authorization: Bearer test_token" \
  "http://localhost:8080/2/tweets/search/recent?query=hello"
```

Open `http://localhost:8080/playground` in your browser for the interactive UI.

***

## What's included

| Feature                | Description                                     |
| :--------------------- | :---------------------------------------------- |
| **Request validation** | Validates requests against the OpenAPI spec     |
| **Realistic errors**   | Returns proper error codes and messages         |
| **Streaming support**  | Simulated streaming endpoints                   |
| **Rate limiting**      | Configurable rate limit simulation              |
| **CORS support**       | Works with browser-based applications           |
| **Usage tracking**     | Simulated billing and credit tracking endpoints |
| **State persistence**  | Optional file persistence in `~/.playground/`   |

***

## Related

<CardGroup>
  <Card title="xurl" icon="terminal" href="/tools/xurl">
    CLI tool for the real X API with built-in authentication.
  </Card>

  <Card title="Make your first request" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/make-your-first-request">
    Ready for the real API? Make your first request.
  </Card>
</CardGroup>


# Python XDK
Source: https://docs.x.com/tools/python-xdk

Install and use the official Python XDK client library for the X API v2, including authentication setup, paginated requests, and streaming examples.

The [Python XDK](https://github.com/xdevplatform/xdk-python) is the official client library for the X API v2. It handles authentication, pagination, and streaming so you can focus on building.

<Card title="GitHub repository" icon="github" href="https://github.com/xdevplatform/xdk-python">
  Source code, issues, and releases.
</Card>

***

## Installation

```bash theme={null}
pip install xdk
```

Requires Python 3.8+.

***

## Quick start

```python theme={null}
from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Search for posts
for page in client.posts.search_recent(query="X API", max_results=10):
    if page.data and len(page.data) > 0:
        print(page.data[0].text)
        break
```

***

## Key features

| Feature                  | Description                                                           |
| :----------------------- | :-------------------------------------------------------------------- |
| **OAuth support**        | Bearer Token, OAuth 2.0 with PKCE, and OAuth 1.0a                     |
| **Automatic pagination** | Iterate through results without manual `next_token` handling          |
| **Streaming**            | Real-time data via persistent connections (filtered stream, etc.)     |
| **Full API coverage**    | All X API v2 endpoints — search, timelines, filtered stream, and more |

***

## Authentication

<Tabs>
  <Tab title="Bearer Token">
    ```python theme={null}
    from xdk import Client

    client = Client(bearer_token="YOUR_BEARER_TOKEN")
    ```
  </Tab>

  <Tab title="OAuth 2.0">
    ```python title="Example" lines wrap icon="python" theme={null}
    from xdk import Client
    from xdk.oauth2_auth import OAuth2PKCEAuth

    auth = OAuth2PKCEAuth(
        client_id="YOUR_CLIENT_ID",
        redirect_uri="YOUR_CALLBACK_URL",
        scope="tweet.read users.read offline.access"
    )

    auth_url = auth.get_authorization_url()
    tokens = auth.fetch_token(authorization_response=callback_url)
    client = Client(bearer_token=tokens["access_token"])
    ```
  </Tab>

  <Tab title="OAuth 1.0a">
    ```python theme={null}
    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)
    ```
  </Tab>
</Tabs>

***

## Common methods

| Category   | Method                         |
| :--------- | :----------------------------- |
| **Posts**  | `client.posts.search_recent()` |
| **Users**  | `client.users.get_me()`        |
| **Spaces** | `client.spaces.get()`          |
| **Lists**  | `client.lists.get()`           |
| **DMs**    | `client.direct_messages.get()` |

***

## Learn more

<CardGroup>
  <Card title="Installation" icon="download" href="/xdks/python/install">
    Development install, prerequisites, and verification.
  </Card>

  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/xdks/python/quickstart">
    Step-by-step first request walkthrough.
  </Card>

  <Card title="Authentication" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/xdks/python/authentication">
    Detailed guide for all auth methods.
  </Card>

  <Card title="Pagination" icon="arrows-left-right" href="/xdks/python/pagination">
    Automatic pagination and iterators.
  </Card>

  <Card title="Streaming" icon="satellite-dish" href="/xdks/python/streaming">
    Real-time data via filtered stream.
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/xdks/python/reference/modules">
    Complete client and model reference.
  </Card>
</CardGroup>

For code examples, see the [samples repo](https://github.com/xdevplatform/samples/tree/main/python).


# skill.md
Source: https://docs.x.com/tools/skill-md

skill.md is a structured capability summary that describes what AI agents can do with the X API, used by tools like agentskills.io to enable workflows.

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.

***

## What's included

* **Capabilities** — what agents can accomplish (search posts, create posts, manage users, etc.)
* **Skills** — specific actions organized by category with required parameters
* **Workflows** — step-by-step procedures for common tasks
* **Context** — background on authentication, rate limits, and architecture

```bash theme={null}
# Fetch the skill file
curl https://docs.x.com/skill.md
```

***

## Discovery endpoints

Agents can discover skill files programmatically via the well-known endpoints:

```bash theme={null}
# Discovery endpoint (agent-skills 0.2.0 spec)
curl https://docs.x.com/.well-known/agent-skills/index.json

# Original discovery format
curl https://docs.x.com/.well-known/skills/index.json
```

You can add X API capabilities to any agent that supports the [skills CLI](https://www.npmjs.com/package/skills):

```bash theme={null}
npx skills add https://docs.x.com
```


# TypeScript XDK
Source: https://docs.x.com/tools/typescript-xdk

Install and use the official TypeScript XDK client library for the X API v2, with authentication, typed responses, pagination, and streaming examples.

The [TypeScript XDK](https://github.com/xdevplatform/twitter-api-typescript-sdk) is the official client library for the X API v2. Full type safety, automatic pagination, and event-driven streaming.

<Card title="GitHub repository" icon="github" href="https://github.com/xdevplatform/twitter-api-typescript-sdk">
  Source code, issues, and releases.
</Card>

***

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @xdevplatform/xdk
  ```

  ```bash yarn theme={null}
  yarn add @xdevplatform/xdk
  ```

  ```bash pnpm theme={null}
  pnpm add @xdevplatform/xdk
  ```
</CodeGroup>

Requires Node.js 16+ and TypeScript 4.5+ (if using TypeScript).

***

## Quick start

```typescript theme={null}
import { Client } from '@xdevplatform/xdk';

const client = new Client({ bearerToken: 'YOUR_BEARER_TOKEN' });

const userResponse = await client.users.getByUsername('XDevelopers');
console.log(userResponse.data?.username);
```

***

## Key features

| Feature                  | Description                                                      |
| :----------------------- | :--------------------------------------------------------------- |
| **Type safety**          | Complete TypeScript definitions for all endpoints and parameters |
| **Authentication**       | Bearer Token, OAuth 2.0 with PKCE, and OAuth 1.0a                |
| **Automatic pagination** | Async iteration support for paginated endpoints                  |
| **Streaming**            | Event-driven streaming with automatic reconnection               |
| **Full API coverage**    | Users, Posts, Lists, Bookmarks, Communities, and more            |

***

## Authentication

<Tabs>
  <Tab title="Bearer Token">
    ```typescript theme={null}
    import { Client } from '@xdevplatform/xdk';

    const client = new Client({ bearerToken: 'YOUR_BEARER_TOKEN' });
    ```
  </Tab>

  <Tab title="OAuth 2.0">
    ```typescript title="Example" lines wrap icon="square-js" theme={null}
    import { Client, OAuth2, generateCodeVerifier, generateCodeChallenge } from '@xdevplatform/xdk';

    const oauth2 = new OAuth2({
      clientId: 'YOUR_CLIENT_ID',
      clientSecret: 'YOUR_CLIENT_SECRET',
      redirectUri: 'https://your-app.com/callback',
      scope: ['tweet.read', 'users.read', 'offline.access'],
    });

    const codeVerifier = generateCodeVerifier();
    const codeChallenge = await generateCodeChallenge(codeVerifier);
    oauth2.setPkceParameters(codeVerifier, codeChallenge);
    const authUrl = await oauth2.getAuthorizationUrl('state');

    const tokens = await oauth2.exchangeCode(authCode, codeVerifier);
    const client = new Client({ accessToken: tokens.access_token });
    ```
  </Tab>

  <Tab title="OAuth 1.0a">
    ```typescript theme={null}
    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: oauth1 });
    ```
  </Tab>
</Tabs>

***

## Common methods

| Category   | Method                           |
| :--------- | :------------------------------- |
| **Posts**  | `client.posts.search()`          |
| **Users**  | `client.users.getMe()`           |
| **Spaces** | `client.spaces.findSpaceById()`  |
| **Lists**  | `client.lists.getList()`         |
| **DMs**    | `client.directMessages.lookup()` |

***

## Learn more

<CardGroup>
  <Card title="Installation" icon="download" href="/xdks/typescript/install">
    Package managers, TypeScript setup, and requirements.
  </Card>

  <Card title="Authentication" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/xdks/typescript/authentication">
    Detailed guide for all auth methods.
  </Card>

  <Card title="Pagination" icon="arrows-left-right" href="/xdks/typescript/pagination">
    Async iteration and paginated responses.
  </Card>

  <Card title="Streaming" icon="satellite-dish" href="/xdks/typescript/streaming">
    Event-driven streaming with reconnection.
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/xdks/typescript/reference/modules">
    Complete client, interface, and type reference.
  </Card>
</CardGroup>

For code examples, see the [samples repo](https://github.com/xdevplatform/samples/tree/main/javascript).


# xurl — curl-style command line client for the X API
Source: https://docs.x.com/tools/xurl

Install and use xurl, a curl-style CLI for the X API with built-in OAuth that lets you test endpoints, sign requests, and prototype from the terminal.

[xurl](https://github.com/xdevplatform/xurl) is a curl-like command-line tool for the X API. It handles OAuth authentication automatically so you can make API requests without manually managing tokens or signing requests.

<Card title="GitHub repository" icon="github" href="https://github.com/xdevplatform/xurl">
  Source code, releases, and documentation.
</Card>

***

## Installation

Install with Go, or download a pre-built binary from [releases](https://github.com/xdevplatform/xurl/releases).

```bash theme={null}
go install github.com/xdevplatform/xurl@latest
```

***

## Setup

### 1. Create an X app

xurl authenticates using your own developer app. In the [X Developer Portal](https://developer.x.com):

1. Create (or open) an app with **OAuth 2.0** enabled.
2. Register the redirect URI `http://localhost:8080/callback` on the app.
3. Copy the app's **Client ID** and **Client Secret** from the "Keys and tokens" page.

### 2. Set your credentials

Export the credentials in the same shell you'll run xurl from:

```bash theme={null}
export CLIENT_ID="your-x-app-client-id"
export CLIENT_SECRET="your-x-app-client-secret"
```

### 3. Authorize

```bash theme={null}
xurl auth oauth2
```

This opens a browser-based OAuth flow. Once authorized, xurl stores your tokens locally in `~/.xurl` so you don't need to authenticate again.

<Warning>
  If the browser shows **"Something went wrong — You weren't able to give access to the App"**, xurl started the login without valid credentials. Make sure `CLIENT_ID` and `CLIENT_SECRET` are exported in the shell where you ran `xurl auth oauth2`, and that `http://localhost:8080/callback` is registered as a redirect URI on your app.
</Warning>

***

## Usage

### Raw API requests

Use xurl like curl — it handles auth headers automatically:

```bash theme={null}
# Look up a user
xurl /2/users/by/username/xdevelopers

# Search recent posts
xurl "/2/tweets/search/recent?query=from:xdevelopers&max_results=10"

# Create a post
xurl -X POST /2/tweets -d '{"text": "Hello from xurl!"}'
```

### Shortcut commands

xurl includes built-in shortcuts for common operations:

```bash theme={null}
# Look up a user by username
xurl user xdevelopers

# Search recent posts
xurl search "X API"

# Post a tweet
xurl post "Hello from xurl!"
```

***

## Why use xurl?

| Feature              | curl                        | xurl                                  |
| :------------------- | :-------------------------- | :------------------------------------ |
| **Authentication**   | Manual OAuth header setup   | Automatic — just run `xurl auth` once |
| **Token management** | You handle refresh/rotation | Built-in token storage and refresh    |
| **API shortcuts**    | Full URL required           | Shorthand commands for common tasks   |
| **Request signing**  | Manual OAuth 1.0a signing   | Automatic for all requests            |

***

## Using xurl with AI agents

xurl includes a [`SKILL.md`](https://github.com/xdevplatform/xurl/blob/main/SKILL.md) file that describes its capabilities in a machine-readable format. AI agents can use this to understand how to invoke xurl commands on your behalf.

```bash theme={null}
npx skills add https://github.com/xdevplatform/xurl
```

***

## Related

<CardGroup>
  <Card title="Make your first request" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/make-your-first-request">
    Get started with the X API using cURL or SDKs.
  </Card>

  <Card title="API Playground" icon="flask" href="https://github.com/xdevplatform/playground">
    Test endpoints locally with mock data — no API credits needed.
  </Card>
</CardGroup>


# Tutorials
Source: https://docs.x.com/tutorials

X API tutorials covering Postman, Python, R, filtered streaming, full-archive search, webhooks, OAuth authentication, and other common workflows.

<CardGroup>
  <Card title="Explore a user's Posts" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305">
    Learn how to explore a user's Posts and mentions using the user Post timeline and user mention timeline endpoints from the last 7 days.

    <br />

    <br />

    [**View tutorial**](/tutorials/explore-a-users-posts)
  </Card>

  <Card title="Getting started with Postman" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d">
    Learn how to start using Postman to make requests to the X API and X Ads API.

    <br />

    <br />

    [**View tutorial**](/tutorials/postman-getting-started)
  </Card>

  <Card title="Getting started with R and v2 of the X API" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d">
    Learn about using R to connect to the user lookup endpoint and how to work with JSON returned from X API v2.

    <br />

    <br />

    [**View tutorial**](/tutorials/getting-started-with-r-and-v2-of-the-x-api)
  </Card>

  <Card title="Getting historical Posts using the full-archive search endpoint" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834">
    Learn to use the full-archive search endpoint to search the complete history of public X data, build a dataset of geo-tagged Posts, and paginate through results for a query.

    <br />

    [**View tutorial**](/tutorials/getting-historical-posts-using-the-full-archive-search-endpoint)
  </Card>

  <Card title="Post-processing X data with the Google Cloud Platform" icon="cloud">
    Get a high-level overview of how to ingest Posts at scale and use metadata to slice them into specific categories or sub-categories.

    <br />

    [**View tutorial**](/tutorials/post-processing-x-data-with-the-google-cloud-platform)
  </Card>
</CardGroup>


# Explore a user's Posts and mentions with the X API v2
Source: https://docs.x.com/tutorials/explore-a-users-posts

The user Post timeline and user mention timeline endpoints allow developers to retrieve the public Posts composed by, or mentioning a user.

## Introduction

While the [recent search endpoint](/x-api/posts/search/introduction) allows you to only get Posts published in the last 7 days, the user Post timeline and user mention timeline endpoints allow you to retrieve Posts and mentions that are older than the last 7 days, for an authorized user (using the user ID). Developers can use these endpoints to study topics, entities and sentiment of Posts from a user’s timeline or mentions. In this tutorial, we will show you how to explore a user’s Posts and mentions using the user Tweet timeline and user mention timeline endpoints.
 

## Prerequisites

* In order to use the user Tweet timeline and user mention timeline endpoints, you will need to have a valid developer account. 
* You will also need a [Project](/resources/fundamentals/developer-apps) created.
* You must have [signed up](https://developer.x.com/en/portal/petition/essential/basic-info) for a developer account, and have activated the [new Developer Console experience](https://developer.x.com/en/portal/opt-in.html). 
* Access is available with active keys and tokens for a developer App that is attached to a [Project](/resources/fundamentals/developer-apps) created in the [Developer Console](/resources/fundamentals/developer-portal).
* A Bearer Token from your App in the [X Developer Console](/resources/fundamentals/developer-portal).
* If you do not have an approved developer account, you can [apply for one](https://developer.x.com/en/apply-for-access).

## Approved developer account

If you do not have one yet, you can [apply for one](https://developer.x.com/en/apply-for-access).

## Create a Project and connect an App

In the [Developer Console](https://developer.x.com/en/portal/dashboard), click create a new App.

<Frame>
  <img />
</Frame>

Give it a name, select the appropriate use-case, and provide a Project description. Next, you can either create a new App, or connect an existing [App](/resources/fundamentals/developer-apps) (an App is a container for your API keys that you need in order to make an HTTP request to the X API).

<Frame>
  <img />
</Frame>

Click ‘create a new App instead’ and give your App a name in order to create a new App.

<Frame>
  <img />
</Frame>

Once you click complete, you will get your API keys and the bearer token that you can then use to connect to the new endpoints in the X API v2.

<Frame>
  <img />
</Frame>

Click the (+) next to API key, API secret key and Bearer token and copy these values to a safe place on your local machine. You will need these to make the API calls in the next step.

Note: The keys in the screenshot above are hidden, but in your own Developer Console, you will be able to see the actual values for the API key, API secret key and Bearer token.
 

## How to get the user ID for a user to use in the user Tweet timeline and user mention timeline endpoints

The user Tweet timeline and user mention timeline endpoints allow you to get Posts using the user ID. In order to get the user ID from a username, you can use the new [user lookup endpoint v2](/x-api/users/lookup/quickstart/user-lookup). Replace the USER\_NAME with the username of your choice and XXXX with your own bearer token that you obtained above

```bash theme={null}
  curl --request GET 'https://api.x.com/2/users/by/username/USER_NAME --header 'Authorization: Bearer XXXXXX'
```

You will see the user ID in response as shown below:

```json theme={null}
{
   "data": {
       "id": "2244994945",
       "name": "Developers",
       "username": "XDevelopers"
   }
}
```

## Connecting to the user Tweet timeline and user mention timeline endpoints

In order to get the user Tweet timeline for a user, run the following curl command in your terminal (make sure to replace the USER\_ID with the user ID of your choice and XXXX with your own bearer token that you obtained above)

```bash theme={null}
curl --request GET 'https://api.x.com/2/users/USER_ID/tweets' --header 'Authorization: Bearer XXXXXX'
```

You will see that the JSON response for these requests contains the ID and text for the Posts by default (example below).

```yaml theme={null}
{
   "id": "1334200897081987072",
   "text": "👀 If you are new to the X API v2, check out this step-by-step guide to making your first request https://t.co/4rZqThpSbp"
}
```

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).
 

## Exploring the user’s Posts

Once you know how to get Posts using the user Tweet timeline and user mention timeline endpoints, you can start to explore their Posts. For example, if you wanted to identify common named entities present in a user’s mentions, you can do the following:

In the API request, specify that you want the context\_annotations object returned in the Tweet responses:

```bash theme={null}
curl --request GET 'https://api.x.com/2/users/USER_ID/mentions?tweet.fields=context_annotations' --header 'Authorization: Bearer XXXXXX'
```

In the response, you will see if any named entities are present in the mentions. Here is an example:

```json theme={null}
{
   "domain": {
       "id": "47",
       "name": "Brand",
       "description": "Brands and Companies"
   },
   "entity": {
       "id": "783214",
       "name": "X"
   }
}
```

If you wanted to see which popular entities appear in your mentions, you could keep a count of popular entities by parsing each Tweet in the mentions.

If you wanted to explore the preview image URL for all Posts in your timeline that contain media, you can do the following:

In the API request, specify that you want the preview\_image\_url in the tweet.media fields, and the attachments.media\_keys expansions

```bash theme={null}
curl --request GET 'https://api.x.com/2/users/2244994945/mentions?max_results=100&media.fields=preview_image_url&expansions=attachments.media_keys' --header 'Authorization: Bearer XXXXXX'
```

In the response, you will see the preview\_image\_url in the includes object as shown below:

```json theme={null}
{
   "includes": {
       "media": [
           {
               "media_key": "16_1334657439640121344",
               "preview_image_url": "https://pbs.twimg.com/tweet_video_thumb/EoWn3rqU8AAtFWL.jpg",
               "type": "animated_gif"
           }
       ]
   }
}
```

Once you have an understanding of how to navigate a user’s Posts, you can also use other APIs and services to do more with the Posts. Below are some resources to keep handy when using the user Tweet timeline and user mention timeline endpoints.

## Resources

* Learn more about the [user Tweet timeline and the user mention timeline endpoints](/x-api/posts/timelines/introduction).
* Check out the [API reference for the user Tweet timeline endpoint](/x-api/users/get-posts) to learn more about what’s available.
* Check out the [API reference for the user mention timeline endpoint](/x-api/users/get-mentions) to learn more about what’s available.
* Get inspired by reading our other [tutorials](/tutorials).


# Get historical Posts with full-archive search
Source: https://docs.x.com/tutorials/getting-historical-posts-using-the-full-archive-search-endpoint

Step-by-step tutorial for retrieving historical Posts back to 2006 using the X API v2 full-archive search endpoint, query operators, and pagination.

## Introduction

The [Search Posts endpoints](/x-api/posts/search/introduction)
in the v2 world enable you to receive Posts related to topics of interest,
based on a search query that you produce. We have two different endpoints
available with v2 Search Posts: recent search, which is available to all
developers with an approved account and can search for Posts up to seven days
old, and full-archive search, which is only available to
researchers approved for the
[Academic Research product track](https://developer.x.com/en/products/x-api/early-access/guide#na_2),
and can search through the entire archive of Posts dating back to March 2006.

You can see our full search offering on our
[search overview page](/x-api/posts/search/introduction).

These Search Posts endpoints address one of the most common use cases for
academic researchers, who might use this for longitudinal studies, or analyzing
a past topic or event.

This tutorial provides a step-by-step guide for researchers who wish to use the
full-archive search endpoint to search the complete history of public X
data. It will also demonstrate the different ways to build a dataset, such as by
retrieving geo-tagged Posts, and how to page through the available Posts for a
query.

### Prerequisites

Currently, this endpoint is only available as part of the
[Academic Research product track](https://developer.x.com/en/solutions/academic-research/products-for-researchers).
In order to use this endpoint, you must
[apply for access](https://developer.x.com/en/portal/petition/academic/is-it-right-for-you).
Learn more about the
[application and requirements for this track](https://developer.x.com/en/solutions/academic-research/application-info).

### Connect an app to the academic project

Once you are approved to use the Academic Research product track, you will see
your Academic [Project](/resources/fundamentals/developer-apps) in the
[Developer Console](https://developer.x.com/en/portal/dashboard). From the
"Apps" section, click on "Add App" to connect your
[X App](/resources/fundamentals/developer-apps) to the Project.

[](https://res.cloudinary.com/practicaldev/image/fetch/s--gHFOyuDc--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to-uploads.s3.amazonaws.com/i/gb7aevhqyfvfjznd0pnd.png)

![This image displays an Academic Project in the Developer Console that does not have an App added to it yet](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/tutorials/getting-historical-tweets-using-the-full-archive-search-endpoint/dev-portal-1.png.twimg.1920.png)

Then, you can either choose an existing App and connect it to your project (as
shown below).

![This image shows you the page that pops up when you try to add an App to your Academic Project](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/tutorials/getting-historical-tweets-using-the-full-archive-search-endpoint/dev-portal-2.png.twimg.1920.png)

Or you can create a new App, give it a name and click complete, to connect a new
App to your Academic Project.

![This image shows you the page where you will enter a name for your new App, or enables you to select an existing App](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/tutorials/getting-historical-tweets-using-the-full-archive-search-endpoint/dev-portal-3.png.twimg.1920.png)

This will give you your API keys and
[Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token) that you can
then use to connect to the full-archive search endpoint.

![This image shows you the page that you are shown after you create a new App that displays your keys and tokens](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/tutorials/getting-historical-tweets-using-the-full-archive-search-endpoint/dev-portal-4.png.twimg.1920.png)

**Please note**

The keys in the screenshot above are hidden, but in your own Developer Console,
you will be able to see the actual values for the API Key, API Secret Key, and
Bearer Token. Save these keys and the Bearer Token because you will need those
for calling the full-archive search endpoint.

### Connecting to the full-archive search endpoint

The cURL command below shows how you can get historical Posts from @XDevelopers
handle. Replace the \$BEARER\_TOKEN with your own Bearer Token, paste the full
request in your terminal, and press "return".

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers' --header 'Authorization: Bearer $BEARER_TOKEN'
```

You will see the response JSON.

By default, only the 10 most recent Posts will be returned. If you want more
than 10 Posts per request, you can use the max\_results parameter and set it to
a maximum of 500 Posts per request, as shown below:

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'
```

### Building queries

As you can see in the example calls above, using the query parameter, you can
specify the data that you want to search for. As an example, if you wanted to
get all Posts that contain the word *covid* or the word *coronavirus*, you can
use the OR operator within brackets, and your query can be
`(covid OR coronavirus)` and thus your API call will look like the following:

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=(covid%20OR%20coronavirus)&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'
```

Similarly, if you want all Posts that contain the words *covid19* that are not
reposts, you can use the is:retweet operator with the logical NOT (represented
by -), so your query can be covid19 -is:retweet and your API call will be:

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=covid19%20-is:retweet&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'
```

Check out
[this guide for a complete list of operators](/x-api/posts/search/integrate/build-a-query)
that are supported in the full-archive search endpoint.

### Using the start\_time and end\_time parameters to get historical Posts

When using the full-archive search endpoint, by default Posts from the last 30
days will be returned. If you want to get Posts that are older than 30 days,
you can use the start\_time and end\_time parameters in your API call. These
parameters must be in a valid RFC3339 date-time format, for example
2020-12-21T13:00:00.00Z. Thus, if you want to get all Posts from the XDevelopers
account for the month of December 2020, your API call will be:

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:XDevelopers&start_time=2020-12-01T00:00:00.00Z&end_time=2021-01-01T00:00:00.00Z' --header 'Authorization: Bearer $BEARER_TOKEN'
```

### Getting geo-tagged historical Posts

Geo-tagged Posts are Posts that have geographic information associated with
them such as city, state, country etc.

#### Using has:geo operator

If you want to get Posts that have geo data, you can use the has:geo operator.
For example, the following cURL request will get only those Posts from the
@XDevelopers handle that have geo data:

```bash theme={null}
curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20has:geo' --header
'Aubashthorization: Bearer $BEARER_TOKEN'
```

#### Using place\_country operator

Similarly, you can limit Posts that have geo data, to a specific country, using
the place\_country operator. The cURL command below will get all Posts from the
@XDevelopers handle from the United States:

```bash theme={null}
curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20place_country:US'
--hbasheader 'Authorization: Bearer XXXXX'
```

The country is specified above using the ISO alpha-2 character code. Valid ISO
codes can be found [here](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

### Getting more than 500 historical Posts using the next\_token

As mentioned above, by default you can only get up to 500 Posts per request for
a query to the full-archive search endpoint. If there are more than 500 Posts
available for your query, your json response will include a next\_token which you
can append to your API call in order to get the next available Posts for this
query. This next\_token is available in the meta object of your JSON response,
which looks something:

```json theme={null}
{ "newest_id": "12345678...", "oldest_id": "12345678...", "result_count": 500,
"nebashxt_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
```

Hence, to get the next available Posts, use the next\_token value from this meta
object and use the value as the value for the next\_token in your API call to the
full-archive search endpoint as shown below (You will use your own Bearer Token
and the value that you get for the Next Token for your previous API call).

```bash theme={null}
curl --request GET
'https://api.x.com/2/tweets/search/all?max_results=500&query=covid&next_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
--header 'Authorization: Bearer $BEARER_TOKEN'
```

This way, you can keep checking if a next\_token is available and if you have not
reached your desired number of Posts to be collected, you can keep calling the
full-archive endpoint with the new next\_token for each request.

Below are some resources that can help you when using the full-archive search
endpoint. We would love to hear your feedback. Reach out to us on
[@XDevelopers](https://x.com/XDevelopers) or on our
[community forums](https://devcommunity.x.com/) with questions about this
endpoint.

### Additional resources

* [Full-archive search endpoint API reference](/x-api/posts/full-archive-search)
* [Learn the basics of building a search query](/x-api/posts/search/integrate/build-a-query)


# Getting started with R and v2 of the X API
Source: https://docs.x.com/tutorials/getting-started-with-r-and-v2-of-the-x-api

Tutorial for calling the X API v2 user lookup endpoint from R using httr and jsonlite, including bearer token setup and parsing JSON responses in R.

## Introduction

This tutorial will walk through what you need to get started with the
programming language R and the X API v2. Using R to connect to the
[user lookup](/x-api/users/lookup/introduction) endpoint, I'll show how to work
with JSON returned from the X API. User lookup is a GET method and returns
information about a user or group of users, specified by a user ID or a
username.

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/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.

### Getting started with the X API

Before you can use the X API v2, you will need to
[sign up](https://developer.x.com/en/portal/petition/essential/basic-info)
for a developer account.

Once you have an approved developer account, you will need to first create a
[Project](/resources/fundamentals/developer-apps). Projects allow you to organize your work
based on how you intend to use the X API, so you can effectively manage
your access to the API, and monitor your usage.

Each Project contains an [App](/resources/fundamentals/developer-apps), with which you can
generate the credentials required to use the X API. You can learn more
about how to get started with the X API, in the
[getting started](/x-api/getting-started/about-x-api) section of our
documentation.

### Getting your R environment set up

First, you need to [download R](https://cloud.r-project.org/) which you can do
on the [cran website.](https://cran.r-project.org/)

After, to set up an environment to work with R, you can use
[R studio](https://www.rstudio.com/), the R extension pack for
[Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=Ikuyadeu.r-pack),
or a
[Jupyter notebook](https://docs.anaconda.com/anaconda/navigator/tutorials/r-lang/)
if you come from the Python world.

### Setting up your environment variable

For the code examples, I'm going to be showing today, you will want to create an
environment variable for your bearer token. The Bearer Token is what allows you
to authenticate to the X API and start making requests. First, replace
“your-bearer-token” with your own bearer token, which can be obtained from the
keys and tokens section of your App in the Developer Console. You'll need to run
this line of code in the console before you start writing a script.

```r theme={null}
Sys.setenv(BEARER_TOKEN = "your-bearer-token")
```

### Making your request

You can use the package
[httr](https://cran.r-project.org/web/packages/httr/index.html) to make HTTP
requests to the X API. If you haven't already installed this, please
install the package in your console. You will also need to install
[jsonlite](https://cran.r-project.org/web/packages/jsonlite/index.html) to work
with our JSON object and [dplyr](https://dplyr.tidyverse.org/) for data
manipulation.

```r theme={null}
install.packages("httr")
install.packages("jsonlite")
install.packages("dplyr")
```

You can now begin writing your R script to connect to the API. At the top of the
file, call the packages httr, jsonlite, and dplyr.

```r theme={null}
require(httr)
require(jsonlite)
require(dplyr)
```

The first step in your code sample is to get set up to authenticate to the
X API. Grab the
[Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token) you pulled from
your App, and pass that into your headers for authentication. In the below
example, replace \$BEARER\_TOKEN with your token.

```r theme={null}
bearer_token <- Sys.getenv("$BEARER_TOKEN")
headers <- c(`Authorization` = sprintf('Bearer %s', bearer_token))
```

Once you got your authentication set up, define the parameters of your request.
By default, you will get back the id, name, and username of each user you get
back. You can make adjustments to this payload by adding additional
[fields](/x-api/fundamentals/fields) and
[expansions](/x-api/fundamentals/expansions). For this example, you will want
the profile bio of the user which is requested using user.fields=description,
and an expansion that contains the pinned Post of the user.

```r theme={null}
params <- list(`user.fields` = 'description', `expansions` = 'pinned_tweet_id')
```

Now you are ready to format your URL with the X handle, also known as
account, you are looking to get more information about. Use the readline method
to allow this sample to be reusable. After you type the handle you want to look
at, format your URL to contain the handle you define by replacing \$USERNAME with
the desired X handle.

```r theme={null}
handle <- readline('$USERNAME')
url_handle <- sprintf('https://api.x.com/2/users/by?usernames=%s', handle)
```

At this point, use the httr package to make a GET request to the URL you just
created, pass in our authentication credential via the header, and pass in the
parameters you defined. You can save the response as a text object in the
variable obj and print this out to view the result of the request you made.

```r theme={null}
response <-
  httr::GET(url = url_handle,
    httr::add_headers(.headers = headers),
    query = params)
obj <- httr::content(response, as = "text")
print(obj)
```

### Working with our JSON payload

One of my favorite ways to work with a JSON is to use a data frame, which allows
you to easily access complex nested data. To do this, use the fromJSON method of
the jsonlite package to flatten your file to allow the fields to be in the same
object. Then, pass that object into a data frame. Now you are ready to view this
data frame.

```
json_data <- fromJSON(obj, flatten = TRUE) %>% as.data.frame View(json_data)
```

You can access the fields of the data from the data frame and pass them into a
string that has the handle, the username, and bio.

```r theme={null}
final <-
  sprintf(
    "Handle: %s\nBio: %s\nPinned Post: %s",
    json_data$data.username,
    json_data$data.description,
    json_data$includes.tweets.text
  )
```

Use cat instead of print to view the object with newlines between each field you
are pulling.

```r theme={null}
cat(final)
```

If you had multiple handles you made requests for, you could easily use a loop
to access each data frame element.

### Conclusion

Hopefully, this tutorial can be a starting place to work with R and the X
API. As a next step, you may want to look at our R samples for recent search,
Post lookup and user lookup in our
[v2 sample code](https://github.com/xdevplatform). Be sure to let us know on the
[forums](https://devcommunity.x.com/) if you run into any troubles along the
way or Post us at [@XDevelopers](https://x.com/XDevelopers) if this
tutorial inspires you to create anything.


# Post-processing X data with the Google Cloud Platform
Source: https://docs.x.com/tutorials/post-processing-x-data-with-the-google-cloud-platform

Post-processing X data with the Google Cloud Platform. Documentation for the X developer platform covering post processing x data with the google cloud.



# Getting started with Postman
Source: https://docs.x.com/tutorials/postman-getting-started

Get started with Postman for the X API, including installing Postman, importing the X API collection, configuring OAuth, and sending your first request.

## Introduction

Postman is a desktop and web application that lets you make requests to an API from a graphical user interface. We recommend using Postman with the X API, X Ads API, and Labs endpoints when you explore API functionality or troubleshoot issues with your application.

We currently have two Postman collections available:

<CardGroup>
  <Card title="X API v2 Collection" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80" />

  <Card title="X Ads API Collection" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87" />
</CardGroup>

### Prerequisites

Before you start with X's Postman collections, make sure you have the right access and credentials for the X developer platform tool you plan to use. See the [Getting started](/overview) page for more on access.

You'll need the following before you continue:

* A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info).
* A [developer App](/resources/fundamentals/developer-apps).
* A set of [authentication](/resources/fundamentals/authentication) keys and tokens.
* An environment configured to make requests to the API you plan to use.

## Getting started with X's Postman collections

### Step one: Add one of the X Postman collections to your account

You could build out specific endpoints in Postman yourself, but we've done the heavy lifting for you. Select one of the links in the [Postman collections](#introduction) section above and a ready-to-use collection with all of the endpoints for the selected API is added to your Postman app. These collections are also available in the [Postman API network](https://explore.postman.com/).

Each endpoint comes preconfigured with available parameters, example responses, and authentication type. You only need to add your credentials and parameter values to start exploring.

In this example, we'll work with the X [API v2 collection](https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80).

### Step two: Add your keys and tokens as environmental variables

When you add the collection to your Postman instance, it automatically creates an environment called "X API v2". You need to add your keys and tokens to this environment. In this step, we'll walk you through adding the keys and tokens from your developer App into the "X API v2" environment.

To add your keys and tokens, select the "manage environments" button in the top right corner of Postman.

<Frame>
  <img alt="This image shows the &#x22;manage environments&#x22; button highlighted in the Postman console." />
</Frame>

From the list of environments, select "X API v2".

Next, add a variable for each of the keys and tokens you generated in the Apps dashboard. Here is an example of what your table should look like:

| VARIABLE         | INITIAL VALUE                                                     | CURRENT VALUE                                                     |
| :--------------- | :---------------------------------------------------------------- | :---------------------------------------------------------------- |
| consumer\_key    | `QAktM6W6DF6F7XXXXXX`                                             | `QAktM6W6DF6F7XXXXXX`                                             |
| consumer\_secret | `AJX560A2Omgwyjr6Mml2esedujnZLHXXXXXX`                            | `AJX560A2Omgwyjr6Mml2esedujnZLHXXXXXX`                            |
| access\_token    | `1995XXXXX-0NGqVhk3s96IX6SgT3H2bbjOPjcyQXXXXXXX`                  | `1995XXXXX-0NGqVhk3s96IX6SgT3H2bbjOPjcyQXXXXXXX`                  |
| token\_secret    | `rHVuh7dgDuJCOGeoe4tndtjKwWiDjBZHLaZXXXXXX`                       | `rHVuh7dgDuJCOGeoe4tndtjKwWiDjBZHLaZXXXXXX`                       |
| bearer\_token    | `AAAAAAAAAAAAAAAAAAAAAL9v6AAAAAAA99t03huuqRYg0mpYAAFRbPR3XXXXXXX` | `AAAAAAAAAAAAAAAAAAAAAL9v6AAAAAAA99t03huuqRYg0mpYAAFRbPR3XXXXXXX` |

The keys and tokens in the table above are not real and will not work in a request.

Once you've added your credentials as variables and made sure that the X API v2 environment is selected, you're ready to make requests to the X API v2 collection. Each endpoint's authorization tab inherits the variables from this environment automatically.

To use Postman with user access tokens, skip ahead to [Generating a user access token with Postman](#generating-a-user-access-token-with-postman).

### Step three: Select an endpoint

Next, choose an endpoint from the collection and build your request. You can select an endpoint from the right-hand side navigation. Here is what this looks like:

<Frame>
  <img alt="This image shows the &#x22;Single Posts&#x22; request selected under the &#x22;Post Lookup&#x22; dropdown in the &#x22;X API v2&#x22; section." />
</Frame>

For this example, we'll use the X API v2 > Post Lookup > Single Post endpoint.

#### Step four: Add values to the Params tab

Next, navigate to the Params tab. You should see a set of inactive params with descriptions that explain what each parameter does and a list of the values you can pass with your request.

In this example, we'll activate the `expansions` and `tweet.fields` query parameters and add the following values:

|                |                          |
| :------------- | :----------------------- |
| **Key**        | **Value**                |
| `tweet.fields` | `created_at,attachments` |
| expansions     | author\_id               |

In addition to the query parameters, you need to add the required path variable, `id`. Since this endpoint returns Posts, add a valid Post ID as the value.

You can find the Post ID by navigating to x.com, selecting a Post, and looking at the URL. For example, the following URL's Post ID is `1228393702244134912`:

`https://x.com/XDevelopers/status/1228393702244134912`

On the Params tab, scroll down past the query parameters to display the "Path Variables" section. Add the Post ID you want to use as the value for the `id` key.

If you entered everything correctly, the Params tab should look like the following:

<Frame>
  <img alt="This image shows the &#x22;Params&#x22; table filled out based on the instructions included earlier in the page." />
</Frame>

#### Step five: Send your request and review your response

Now that your request is set up, select the "Send" button.

If everything was set up properly, you should receive the following payload:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
    "data": {
        "author_id": "2244994945",
        "text": "What did the developer write in their Valentine's card?\n  \nwhile(true) {\n    I = Love(You);  \n}",
        "id": "1228393702244134912",
        "created_at": "2020-02-14T19:00:55.000Z"
    },
    "includes": {
        "users": [
            {
                "username": "XDevelopers",
                "name": "Developers",
                "id": "2244994945"
            }
        ]
    }
}
```

### Generating a user access token with Postman

#### Using OAuth 1.0a to generate a user access token

Review the three-step process used in the [OAuth 1.0a flow test collection](https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80).

#### Using OAuth 2.0 to generate a user access token

You can generate OAuth 2.0 access tokens to use with the X [API v2 Postman collection](https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80).

Select the collection in your workspace, go to the "Auth" tab, and set the type to "OAuth 2.0". Under "Configure New Token", find "Configuration Options" and update the "Grant Type" to "Authorization Code (With PKCE)".

Update your Callback URL to match the callback URL associated with your application. Also update the following parameters:

* Auth URL — `https://x.com/i/oauth2/authorize`
* Access Token URL — `https://api.x.com/2/oauth2/token`
* Client ID — Your OAuth 2.0 client ID from the Dev Portal
* Client Secret — If you are using a confidential client
* Scope — Scopes to match the endpoints you want to connect to. For example: `tweet.read users.read`
* Your callback URL (also known as the redirect URL). This must match the value in your App's authentication settings.
* State — state

When you're ready, select "Get New Access Token" to generate an access token. If you see a dialog box that says something went wrong, you may need to select the back button to log in. You'll need to authorize your app to access your account by selecting "Authorize app" in the dialog box.

After you authorize your app, you're directed back to Postman, where you can see your token and select the "Use Token" button to start making requests on behalf of an authorized user.

You're now ready to use the Postman collection.

## What's next

Select the "Code" button in Postman to turn the request into the language of your choice, such as Python, Node, or Ruby, to help you get started. Postman has [great documentation](https://learning.getpostman.com/) that may be helpful. We also have [sample code on GitHub](https://github.com/xdevplatform) to help you integrate with the endpoints more quickly.


# Build for businesses
Source: https://docs.x.com/use-cases/build-for-business

How businesses use the X API for social listening, customer service, brand monitoring, market intelligence, and data-driven decision making at scale.

## Listen to the conversation on x

<CardGroup>
  <Card title="Monitor your brand" icon="eye">
    Understand, track, and benchmark the conversations and perceptions surrounding your brand.

    [**Learn more**](https://developer.x.com/en/use-cases/build-for-businesses/brand-monitoring) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>

  <Card title="Track events" icon="calendar">
    Stay on top of breaking news and events to spot crises early that might impact your business and brand reputation.

    [**Learn more**](https://developer.x.com/en/use-cases/build-for-businesses/track-events) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>
</CardGroup>

## Use insights from X

<CardGroup>
  <Card title="Manage your social media" icon="share-nodes">
    Manage and track every aspect of your social presence with targeted tooling and real-time ROI.

    [**Learn more**](https://developer.x.com/en/use-cases/build-for-businesses/manage-social-media) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>

  <Card title="Oversee customer care" icon="globe">
    Directly engage with your customers to quickly answer questions, resolve their issues, and provide exceptional service.

    [**Learn more**](https://developer.x.com/en/use-cases/build-for-businesses/customer-care-management) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>
</CardGroup>

## Discover new trends and opportunities

<CardGroup>
  <Card title="Uncover consumer insights" icon="magnifying-glass-chart">
    Inform your business strategy with insights into emerging trends, customer preferences, and feedback.
  </Card>

  <Card title="Inform search results" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834">
    Enhance your search results with what’s happening on X.
  </Card>

  <Card title="Research markets and audiences" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980">
    Understand your audience and what they value by uncovering trends and surfacing important conversations on X.

    [**Learn more**](https://developer.x.com/en/use-cases/build-for-businesses/market-research) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>
</CardGroup>

## Expand what’s possible with X Ads

<CardGroup>
  <Card
    title="Enrich advertising solutions on X
"
    icon="bullhorn"
  >
    Enhance the X Ads experience with unique innovations and efficiencies for advertisers.

    [**Learn more**](https://developer.x.com/en/use-cases/build-for-businesses/advertise) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>
</CardGroup>

## Build for publishers

<CardGroup>
  <Card title="Embed X content" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219">
    Engage your users with live X content that brings context to what’s happening and links to the source. Amplify your efforts on X by embedding your X content into your website or app.

    [**Learn more**](https://developer.x.com/en/products/x-for-websites) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>
</CardGroup>


# Build for the public
Source: https://docs.x.com/use-cases/build-for-consumers

Build consumer apps with the X API that enhance how people post, follow, search, and engage on X, from utilities and chatbots to creator tools.

## Ways to build for people on X

We are opening up our platform to encourage you to build new tools and products that have a positive impact on the public conversation and serve people on X. Specifically, we want to encourage new innovation and development in the following areas:

<CardGroup>
  <Card title="Moderate conversations for health and safety" icon="bullhorn">
    Improve the health and safety of public conversation. Build content moderation tools and other solutions that help people feel safe and excited to participate on X. Create complementary technology that gives people a comprehensive choice of tools to control their int

    [**Learn more**](/x-api/what-to-build#moderate-conversations-for-health-and-safety) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>

  <Card title="Enable creation and personal expression" icon="bullhorn">
    Build tools for creators, brands, and individuals who want to extend their reach, express their brand, and connect with people that share their passion. Or broaden the ways people can engage on X like cross-posted content, gamification, or helpful bots.

    [**Learn more**](/x-api/what-to-build#enable-creation-and-personal-expression) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>

  <Card title="Measure and analyze “what’s happening”" icon="bullhorn">
    Help people measure, analyze, and derive insights from the public conversation or their own content. Understand your audience better, measure the performance and impact of your content, make more informed decisions, and so much more.

    [**Learn more**](/x-api/what-to-build#measure-and-analyze-whats-happening) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>

  <Card title="Improve community experiences " icon="bullhorn">
    X is for everyone, and we want to empower you to use your expertise to serve the unique needs of different communities on X. Whether you're building localized solutions for emerging global markets or enhancing experiences for communities like gaming or finance, we want everyone to find their place on X.

    [**Learn more**](/x-api/what-to-build#improve-community-experiences) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>

  <Card title="Curate and recommend content" icon="bullhorn">
    Build apps, bots, or other tools that help people discover new content or make new connections. Or build curated and customizable experiences so people see more of the content they care most about.

    [**Learn more**](/x-api/what-to-build#curate-and-recommend-content) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>

  <Card title="Impact the greater good" icon="bullhorn">
    Conduct groundbreaking research, help advance knowledge about public health and the climate crises and build non-commercially for the greater good.

    [**Learn more**](/x-api/what-to-build#impact-the-greater-good) <Icon icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" />
  </Card>
</CardGroup>


# Build for fun
Source: https://docs.x.com/use-cases/build-for-fun

Hobbyist projects to build with the X API, from creative bots and IoT installations to art projects, games, and weekend hacks using real-time data.

## Explore new ways to build for fun

<CardGroup>
  <Card title="Create art">
    Share your creative energy with the world. Build interactive experiences that spark joy and provoke conversation.
  </Card>

  <Card title="Connect hardware or gadgets">
    A plant that posts when it needs water? A doorbell that sends you a DM instead
    of ringing? These are just some of the fun things that developers have built
    to connect X to the internet of things.
  </Card>

  <Card title="Explore the API">
    Explore all of the corners of the global conversation to learn something new,
    get an idea, and broaden perspectives.
  </Card>

  <Card title="Manage or automate your X account">
    Schedule posts, engage with your timeline, or make new connections with a few
    lines of code.
  </Card>

  <Card title="Keep X weird">
    Be yourself, the more obscure the better. That’s X.
  </Card>
</CardGroup>


# Build for good
Source: https://docs.x.com/use-cases/build-for-good

Use the X API for social good, from nonprofit tools and emergency response to community safety, public health, and civic engagement projects.

## Use data to create change

<CardGroup>
  <Card title="Connect communities">
    Build tools to bring communities closer during events like #SuperBowl and #GRAMMYs, or all year long with topics like #BlackLivesMatter, #BTS, and #TigerKing.
  </Card>

  <Card title="Share information">
    Keep people safe and informed with tools to automatically share information
    like extreme weather updates, public health notices, and more.
  </Card>

  <Card title="Improve X">
    Make X better for the people who use it. You've played a key part in making X healthier and more engaging since the beginning, and we want to continue to earn and facilitate your creative energy.
  </Card>
</CardGroup>


# Do research
Source: https://docs.x.com/use-cases/do-research

Use the X API for academic and market research with access to historical and real-time data, full-archive search, filtered streams, and analytics endpoints.

## Listen to and understand what's happening on X

<CardGroup>
  <Card title="Conduct academic research">
    From social science to computer science, advance nearly any research objective
    on topics as diverse as the global conversations happening on X.
  </Card>

  <Card title="Solve problems with applied research for NGOs">
    Use X data to conduct scientific studies that solve problems to impact the
    mission of your non-profit organization or lab.
  </Card>

  <Card title="Enrich investigative journalism and independent research">
    Use X data to explore global to local topics and events that can inform
    projects and publications.
  </Card>

  <Card title="Conduct market research for business">
    Understand your audience and what they value by uncovering trends and
    surfacing important conversations on X.
    important conversations on X.
  </Card>
</CardGroup>


# Teach and learn
Source: https://docs.x.com/use-cases/teach-and-learn

Use the X API in classrooms and curricula to teach API design, data analysis, social media research, and software engineering with real-world data.

## Educators

Bring the API into your classroom to teach students programming fundamentals and
valuable data processing skills.

**Resources:**

Are you an educator looking to use X API in your course? This
[guide to teaching with the X API](https://dev.to/suhemparack/a-guide-to-teaching-with-the-twitter-api-v2-3n08)
will help you understand the X API, why it's used by educators, what type of
classes are being taught with the API, and everything else you need to know to
get started.

**Spotlight:**

The below curriculums are built and executed using the X API v2:

* [Social Media Data Mining and Analysis](https://canvas.uw.edu/courses/1434897)
  by Dr. Tanu Mitra

* [Data Science & Society](https://dssoc.github.io/) by Dr. Chris Bail

* [Introduction to Cultural Analytics & Python](https://melaniewalsh.github.io/Intro-Cultural-Analytics/welcome.html)
  by Dr. Melanie Walsh

* [Oxford Spring School in Advanced Research Methods, Analysing X Data](https://github.com/cjbarrie/oxspsch)
  by Dr. Chris Barrie

<hr />

## Students

Complete an assignment, learn to process and analyze data, or even post your
first “Hello, world!”

[Become a X Student Ambassador](https://developer.x.com/en/community/student-ambassadors)


# What to Build
Source: https://docs.x.com/what-to-build

Project ideas and use cases for the X API, from chatbots and analytics dashboards to content moderation, research tools, and community apps.

The X API opens up possibilities across moderation, analytics, community building, and more. Here are ideas to inspire your next project.

***

## Build for safety & moderation

Help create healthier conversations on X.

<CardGroup>
  <Card title="Moderation tools" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055">
    Build tools to help users manage replies, filter content, and protect their experience.
  </Card>

  <Card title="Anti-harassment" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-block.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=702a65b4001948aebcc42635b8e2eac7">
    Detect and flag abusive content, provide bulk blocking tools.
  </Card>
</CardGroup>

**Relevant endpoints:**

* [Blocks](/x-api/users/blocks/introduction) — Block and unblock users
* [Mutes](/x-api/users/mutes/introduction) — Mute accounts and keywords
* [Hide replies](/x-api/posts/hide-replies/introduction) — Hide unwanted replies
* [Manage posts](/x-api/posts/manage-tweets/introduction) — Control reply settings

***

## Build for creators

Help people express themselves and grow their audience.

<CardGroup>
  <Card title="Scheduling tools" icon="calendar">
    Schedule posts, threads, and content calendars.
  </Card>

  <Card title="Cross-posting" icon="share-nodes">
    Sync content across platforms and formats.
  </Card>

  <Card title="Thread creators" icon="layer-group">
    Help users compose and publish long-form threads.
  </Card>

  <Card title="Bots & automation" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-ai-agents.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=53171c3a2a9432187cf705d13e24651b">
    Create helpful bots that add value to the conversation.
  </Card>
</CardGroup>

**Relevant endpoints:**

* [Manage posts](/x-api/posts/manage-tweets/introduction) — Create and delete posts
* [Media upload](/x-api/media/quickstart/media-upload-chunked) — Upload images and videos
* [Spaces](/x-api/spaces/lookup/introduction) — Discover audio conversations

***

## Build for analytics

Help users understand their impact and audience.

<CardGroup>
  <Card title="Performance dashboards" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143">
    Visualize engagement metrics, growth trends, and reach.
  </Card>

  <Card title="Audience insights" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980">
    Analyze followers, engagement patterns, and demographics.
  </Card>

  <Card title="Trend analysis" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-feather-chart-line.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=185e7e1271f798947403bb3f0c44f294">
    Track hashtags, topics, and conversation volume.
  </Card>

  <Card title="Competitive analysis" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143">
    Compare accounts, benchmark performance.
  </Card>
</CardGroup>

**Relevant endpoints:**

* [Metrics](/x-api/fundamentals/metrics) — Engagement and performance data
* [Search posts](/x-api/posts/search/introduction) — Historical and recent search
* [Post counts](/x-api/posts/counts/introduction) — Volume analytics
* [Annotations](/x-api/fundamentals/post-annotations) — Topic classification

***

## Build for communities

Help people connect and organize around shared interests.

<CardGroup>
  <Card title="Community tools" icon="people-group">
    Moderation, member management, and engagement tools.
  </Card>

  <Card title="Event coordination" icon="calendar-check">
    Organize Spaces, live events, and group activities.
  </Card>

  <Card title="Curation" icon="bookmark">
    Aggregate and curate content by topic or interest.
  </Card>

  <Card title="Localization" icon="globe">
    Build tools for specific languages and regions.
  </Card>
</CardGroup>

**Relevant endpoints:**

* [Lists](/x-api/lists/list-lookup/introduction) — Curated account lists
* [Spaces](/x-api/spaces/lookup/introduction) — Audio conversations
* [Follows](/x-api/users/follows/introduction) — Relationship management

***

## Build for research

Analyze public conversations and extract insights.

<CardGroup>
  <Card title="Academic research" icon="microscope">
    Study public discourse, information spread, and trends.
  </Card>

  <Card title="Journalism" icon="newspaper">
    Source stories, verify information, track breaking news.
  </Card>

  <Card title="Market research" icon="magnifying-glass-chart">
    Monitor brand sentiment, industry trends, and competitors.
  </Card>

  <Card title="Data science" icon="brain">
    Train models, analyze networks, study behavior patterns.
  </Card>
</CardGroup>

**Relevant endpoints:**

* [Full-archive search](/x-api/posts/search/introduction) — Search posts back to 2006
* [Filtered stream](/x-api/posts/filtered-stream/introduction) — Near real-time matching posts
* [Post annotations](/x-api/fundamentals/post-annotations) — Entity recognition
* [Conversation ID](/x-api/fundamentals/conversation-id) — Thread reconstruction

***

## Build for good

Use the API to make a positive impact.

<CardGroup>
  <Card title="Crisis response" icon="hand-holding-heart">
    Monitor emergencies, coordinate aid, spread awareness.
  </Card>

  <Card title="Accessibility" icon="universal-access">
    Build tools that make X more accessible to everyone.
  </Card>

  <Card title="Education" icon="graduation-cap">
    Create learning tools, teaching resources, and tutorials.
  </Card>

  <Card title="Civic engagement" icon="landmark">
    Help people stay informed and participate in democracy.
  </Card>
</CardGroup>

***

## Build with AI agents

Connect AI tools to the X API and build intelligent workflows.

<CardGroup>
  <Card title="MCP-powered agents" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-ai-agents.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=53171c3a2a9432187cf705d13e24651b">
    Use XMCP to give AI assistants direct access to X API endpoints — create posts, search, and manage accounts via natural language.
  </Card>

  <Card title="Data pipelines" icon="diagram-project">
    Feed X data into LLMs for sentiment analysis, content generation, and automated reporting.
  </Card>

  <Card title="Coding assistants" icon="wand-magic-sparkles">
    Give Grok, Cursor, or your preferred AI tool full context on the X API with llms.txt for faster development.
  </Card>

  <Card title="Custom integrations" icon="plug">
    Build agents that monitor trends, respond to mentions, or curate content automatically.
  </Card>
</CardGroup>

**Get started:**

* [X MCP](/tools/mcp#x-mcp--x-api) — Hosted MCP server for the X API
* [llms-full.txt](https://docs.x.com/llms-full.txt) — Feed complete docs to your AI tool
* [OpenAPI Spec](https://api.x.com/2/openapi.json) — Machine-readable API definition

[Browse all agent resources](/tools/ai)

***

## Getting started

Ready to build? Here's your path forward:

<Steps>
  <Step title="Get access">
    [Sign up for a developer account](/x-api/getting-started/getting-access) and create an app.
  </Step>

  <Step title="Learn the basics">
    [Make your first request](/x-api/getting-started/make-your-first-request) and explore the API.
  </Step>

  <Step title="Choose your tools">
    Pick an [SDK or library](/tools-and-libraries) for your language.
  </Step>

  <Step title="Build and ship">
    Start small, iterate, and share what you've built!
  </Step>
</Steps>

***

## Share your work

Built something with the X API? We'd love to see it:

* Share in the [Developer Forum](https://devcommunity.x.com)
* Tag [@XDevelopers](https://x.com/XDevelopers) on X
* Submit to our [Success Stories](/success-stories)


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

Retrieve campaign performance metrics on the X Ads API using synchronous and asynchronous analytics endpoints with segmentation and granularity options.

<BlueprintMark name="attention" />

Analytics metrics help partners and advertisers understand the performance of the content they promote on X. This includes information such as impressions, clicks, video views, and spend. In addition, partners and advertisers are able to get detailed metrics for various segments of the audiences they reach.

The Ads API supports two ways of retrieving detailed campaign performance metrics: synchronously and asynchronously. With synchronous analytics calls, the requested metrics are returned in the response. With the asynchronous analytics endpoints, the requested metrics are available in a downloadable results file after the associated "job" has finished processing. The synchronous endpoint supports short time ranges and is ideal for real-time campaign optimizations. The asynchronous endpoints support much longer time ranges and are, thus, intended for fetching much more data, ideal for generating reporting or historical backfills.

## Details

### Synchronous vs. Asynchronous

The differences between the synchronous and asynchronous analytics endpoints are summarized in the following table. This information is intended to help developers choose which set of endpoints to use.

| Feature              | Synchronous                                         | Asynchronous                                                 |
| :------------------- | :-------------------------------------------------- | :----------------------------------------------------------- |
| Rate limiting        | User-level: 250 requests / 15 minutes               | Account-level: 100 concurrent\* jobs                         |
| Time range           | 7 days                                              | 90 days (non-segmented)<br />45 days (segmented)             |
| Segmentation         | No                                                  | Yes                                                          |
| Response returns     | Metrics data                                        | Processing state of the job\*\*                              |
| Recommended use case | Real-time optimization<br />User interface requests | Regularly-scheduled syncing<br />Backfilling historical data |

<Note>
  \* This refers to the maximum number of jobs that may be in a processing state at any given time.

  \*\* Once the job has successfully finished processing, a URL is returned. This is where the compressed (gzip) results file can be downloaded from.

  Outside of this, the endpoints offer the same functionality.
</Note>

### Use cases

There are three major analytics use cases.

1. Real-time optimization: using performance metrics to update active campaigns
2. Synchronization: regularly-scheduled background syncs
3. New account on-boarding: backfilling historical data

The synchronous analytics endpoint may be used for real-time optimization to update campaigns based on changes to metrics within the last 5 to 15 minutes. Either endpoint can be used for analytics synchronization. Keep in mind that the desired time range and whether segmentation is required will determine which endpoint to use. New account on-boarding should only be done using the asynchronous analytics endpoints. (The synchronous analytics endpoint should never be used for retrieving large amounts of data.)

The asynchronous analytics endpoints can power dashboards and other UI elements if metrics are synced with a backend process. Your implementation should avoid calling the asynchronous analytics endpoints to fulfill user interface requests.

### Request Options

Analytics requests are scoped to ads accounts and, thus, require the account ID in the resource path. Request options, listed below, are specified as query parameters. The following types of values are required.

* Entities: the entity type as well as up to 20 entity IDs you'd like to request analytics for
* Time range: the start and end times, expressed in ISO 8601
  * **Note:** must be expressed in whole hours
* Metric groups: one or more sets of related metrics (see Metrics and Segmentation for a list of metrics within each metric group)
* Granularity: specifies the level of aggregation in which the metrics should be returned
* Placement: determines whether metrics are pulled for ads that served on or off of X
  * **Note:** only a single placement value can be specified per request

Use the `start_time` and `end_time` request parameters to specify a time range. These values must be aligned with the specified granularity in the following way.

1. `TOTAL`: specify any time range (within the endpoint's limits)
2. `DAY`: both the start time and end time values must be aligned with midnight in the account's time zone
3. `HOUR`: specify any time range (within the endpoint's limits)

End time is exclusive. For example, a request with `start_time=2026-01-01T00:00:00Z` and `end_time=2026-01-02T00:00:00Z` will return a single day's worth of analytics metrics (not two) as this time range covers only a 24 hour period.

**Segmentation**

Available only through our asynchronous analytics endpoints, segmentation allows partners and advertisers to retrieve metrics broken out by particular targeting values. To request segmented metrics, use the `segmentation_type` request parameter. For more details on segmentation options, see [Metrics and Segmentation](/x-ads-api/analytics#metrics-and-segmentation).

## FAQs

Why don't the Ads API numbers match what's shown in the X Ads UI?

* Make sure you've requested data for all placements: `ALL_ON_TWITTER`, `SPOTLIGHT`, and `TREND`.
* Remember that end times in the Ads API are exclusive; they are inclusive in the Ads UI

Why do the numbers change depending on when I request data?

* As soon as reporting metrics are available, you are able to retrieve them. They are available in near real-time. These early results are estimates, though, and, as a result, are expected to change. Metrics are finalized after 24 hours, with the exception of spend data.
* Spend metrics are generally final within 3 days of the event. However, we process billing data for up to 14 days from the date of the event (for spam filtering, for example).

How can I determine which entity IDs to request for a specific time period?

* Use the [Active Entities endpoint](/x-ads-api/analytics#active-entities-2)

Why are all of the values in the analytics response `null`?

* It's likely that the campaign did not serve during the requested time period
* Use the [Active Entities endpoint](/x-ads-api/analytics#active-entities-2) to determine which entities to fetch analytics for and for what time period

Why does the API show `null` values while the UI shows 0s?

* The UI chooses to display these values as 0s, but the values are equivalent

How can I request metrics associated with a granular placement, such as the X timeline?

* We support the following placement values in analytics: `ALL_ON_TWITTER`, `SPOTLIGHT`, and `TREND`

Is it possible to retrieve metrics for deleted or paused entities?

* Yes. The entity's status does not impact the availability of analytics metrics.

Why don't the segmented values match the non-segmented ones?

* Segmented data is *not* expected to roll-up 100% to the non-segmented data, due to how this information is derived.

Why don't the segmented values from the API match what the Ads Manager UI shows?

* The API returns segmented metrics scoped to the specific entity type you query (CAMPAIGN, PROMOTED\_TWEET). The Ads Manager UI aggregates data across entity types. These are different views of the same underlying data and this is expected behavior.

Is it possible to request data segmented by multiple dimensions?

* We do not support multi-segmentation.

## Best Practices

Some best practices when collecting [analytics](/x-ads-api/analytics) data from the Ads API.

### Rate Limiting and Retries

* On queries that are rate limited (those that return an `HTTP 429` status code), you must inspect the `x-rate-limit-reset` header and retry only at or after the time indicated.
* On queries that result in an HTTP 503 Service Unavailable status code, you must inspect the `retry-after` header and retry only after the time indicated.
* Applications that do not respect the times indicated for retries could have their access to the Ads API revoked or throttled without notice.

### Analytics Metrics In a Nutshell

* All analytics metrics are locked and will not change after 24 hours, with the exception of `billed_charge_local_micro`.
* The `billed_charge_local_micro` metric is an estimate for up to 3 days after the data is returned.
* After 24 hours, this metric can decrease due to credits for overspend (ads served after the given `end_time`) and for billable events that are determined to be junk. This metric changes minimally after 24 hours.
* Please see [Analytics](/x-ads-api/analytics) for more information.

### Fetching Real-time, Non-segmented Data

* Always provide both a `start_time` and an `end_time`.
* Do not pull data for any entities older than 7 days.
* Do request data (ideally) with `HOUR` granularity, as you can always aggregate and roll metrics up to get `DAY` and `TOTAL` granularity.
* Do request data (ideally) at the `line_items` and `promoted_tweets` level, as you can always aggregate and roll these metrics up to get totals across the entire ads entity hierarchy (i.e. for the campaign, funding instrument or account levels).
* Save and store the values of analytics metrics on your side (locally).
* Do not repeatedly query for data that is older than 30 days. This data will not change and should be stored locally.
* All non-segmented data is real-time and data should be available within seconds of an event occurring.
* Group conversion metrics and non-conversion metrics into separate requests.

### Fetching Segmented Data

* Refer to guidelines provided for "Fetching Real-time, Non-segmented Data" above. Additional advice provided below.
* For most segmented data types, it is possible for data to not be complete for up to 1 hour at times. Data segmented by `INTERESTS` can be delayed for up to 12 hours.
* Segmented data is not expected to roll-up 100% to the non-segmented data, due to how this information is derived.

### Fetching Historical Data

* When backfilling data (i.e. adding a new advertiser account), you may need to make several requests in smaller `start_time` and `end_time` chunks.
* Limit your fetches to 30-day date windows.
* Throttle these requests and distribute over time so as not to exhaust your rate limits for these fetches.

### Sample

You can find a sample script demonstrating some of these best practices (`fetch_stats`) on our [ads-platform-tools GitHub](https://github.com/xdevplatform/ads-platform-tools) repository.

## Metrics by Objective

Which metrics are applicable for an entity depends on the [campaign objective](/x-ads-api/campaign-management). Use this guide to determine the relevant metric groups to fetch for each objective type, as well as how additional derived metrics can be calculated.

### `ENGAGEMENTS`

**Relevant metric groups:**`ENGAGEMENT` and `BILLING`.

|                 |                                         |
| :-------------- | :-------------------------------------- |
| Derived Metric  | Exposed Metric Calculation              |
| Engagement Rate | `engagements/impressions`               |
| CPE             | `billed_charge_local_micro/engagements` |

### `WEBSITE_CLICKS` and `WEBSITE_CONVERSIONS`

**Relevant metric groups:**`ENGAGEMENT`, `BILLING`, and `WEB_CONVERSION`.

|                   |                                                                                                                          |
| :---------------- | :----------------------------------------------------------------------------------------------------------------------- |
| Derived Metric    | Exposed Metric Calculation                                                                                               |
| CPM               | `billed_charge_local_micro/impressions/1000`                                                                             |
| Click Rate        | `clicks/impressions`                                                                                                     |
| CPLC              | `billed_charge_local_micro/clicks`                                                                                       |
| Total Conversions | `conversion_custom` + `conversion_site_visits` + `conversion_sign_ups` + `conversion_downloads` + `conversion_purchases` |
| Conversion Rate   | Total Conversions / `impressions`                                                                                        |
| CPA               | `billed_charge_local_micro` / Total Conversions                                                                          |

### `APP_INSTALLS`

**Relevant metric groups:**`ENGAGEMENT`, `BILLING`, `MOBILE_CONVERSION`, and `LIFE_TIME_VALUE_MOBILE_CONVERSION`. `VIDEO` is also applicable if video app card is used in creatives.

|                |                                                        |
| :------------- | :----------------------------------------------------- |
| Derived Metric | Exposed Metric Calculation                             |
| CPM            | `billed_charge_local_micro/impressions/1000`           |
| App Click Rate | `app_clicks/impressions`                               |
| CPAC           | `billed_charge_local_micro/app_clicks`                 |
| CPI            | `billed_charge_local_micro/mobile_conversion_installs` |

### `FOLLOWERS`

**Relevant metric groups:**`ENGAGEMENT` and `BILLING`.

|                |                                              |
| :------------- | :------------------------------------------- |
| Derived Metric | Exposed Metric Calculation                   |
| CPM            | `billed_charge_local_micro/impressions/1000` |
| Follow Rate    | `follows/impressions`                        |
| CPF            | `billed_charge_local_micro/follows`          |

### `VIDEO_VIEWS`

**Relevant metric groups:**`ENGAGEMENT`, `BILLING`, and `VIDEO`.

|                |                                               |
| :------------- | :-------------------------------------------- |
| Derived Metric | Exposed Metric Calculation                    |
| CPM            | `billed_charge_local_micro/impressions/1000`  |
| Video Rate     | `video_total_views/impressions`               |
| Cost Per View  | `billed_charge_local_micro/video_total_views` |

### `VIDEO_VIEWS_PREROLL`

**Relevant metric groups:**`ENGAGEMENT`, `BILLING`, and `VIDEO`.

|                |                                               |
| :------------- | :-------------------------------------------- |
| Derived Metric | Exposed Metric Calculation                    |
| CPM            | `billed_charge_local_micro/impressions/1000`  |
| Video Rate     | `video_total_views/impressions`               |
| Cost Per View  | `billed_charge_local_micro/video_total_views` |

## Metrics and Segmentation

This document is an overview of the metrics available from our [Analytics](/x-ads-api/analytics) for each entity type, as well as the available segmentation for each metric.

|                      |                             |                       |                   |                                     |                                           |                                                                           |
| :------------------- | :-------------------------- | :-------------------- | :---------------- | :---------------------------------- | :---------------------------------------- | :------------------------------------------------------------------------ |
|                      | Metric Groups               |                       |                   |                                     |                                           |                                                                           |
| Entity               | [`ENGAGEMENT`](#engagement) | [`BILLING`](#BILLING) | [`VIDEO`](#VIDEO) | [`WEB_CONVERSION`](#WEB_CONVERSION) | [`MOBILE_CONVERSION`](#MOBILE_CONVERSION) | [`LIFE_TIME_VALUE_MOBILE_CONVERSION`](#LIFE_TIME_VALUE_MOBILE_CONVERSION) |
| `ACCOUNT`            | ✔\*                         |                       |                   |                                     |                                           |                                                                           |
| `FUNDING_INSTRUMENT` | ✔\*                         | ✔                     |                   |                                     |                                           |                                                                           |
| `CAMPAIGN`           | ✔                           | ✔                     | ✔                 | ✔                                   | ✔                                         | ✔                                                                         |
| `LINE_ITEM`          | ✔                           | ✔                     | ✔                 | ✔                                   | ✔                                         | ✔                                                                         |
| `PROMOTED_TWEET`     | ✔                           | ✔                     | ✔                 | ✔                                   | ✔                                         | ✔                                                                         |

\*Some metrics in the `ENGAGEMENT` metrics family are not available at the account and funding instrument level. See the `ENGAGEMENT` section for details.

### Available Metrics by Metrics Group

#### `ENGAGEMENT`

|                         |                                                                      |                        |               |                                            |
| :---------------------- | :------------------------------------------------------------------- | :--------------------- | :------------ | :----------------------------------------- |
| Metric                  | Description                                                          | Segmentation Available | Data Type     | Available for Account / Funding Instrument |
| `engagements`           | Total number of engagements                                          | ✔                      | Array of ints | ✔                                          |
| `impressions`           | Total number of impressions                                          | ✔                      | Array of ints | ✔                                          |
| `retweets`              | Total number of reposts                                              | ✔                      | Array of ints | ✔                                          |
| `replies`               | Total number of replies                                              | ✔                      | Array of ints | ✔                                          |
| `likes`                 | Total number of likes                                                | ✔                      | Array of ints | ✔                                          |
| `follows`               | Total number of follows                                              | ✔                      | Array of ints | ✔                                          |
| `card_engagements`      | Total number of card engagements                                     | ✔                      | Array of ints |                                            |
| `clicks`                | Total number of clicks, including favorites and other engagements    | ✔                      | Array of ints |                                            |
| `app_clicks`            | Number of app install or app open attempts                           | ✔                      | Array of ints |                                            |
| url\_clicks             | Total clicks on the link or Website Card in an ad, including earned. | ✔                      | Array of ints |                                            |
| `qualified_impressions` | Total number of qualified impressions                                | ✔                      | Array of ints |                                            |
| `carousel_swipes`       | Total swipes on Carousel images or videos                            | ✔                      | Array of ints |                                            |

#### `BILLING`

|                             |                                    |                        |               |
| :-------------------------- | :--------------------------------- | :--------------------- | :------------ |
| Metric                      | Description                        | Segmentation Available | Data Type     |
| `billed_engagements`        | Total number of billed engagements | ✔                      | Array of ints |
| `billed_charge_local_micro` | Total spend in micros              | ✔                      | Array of ints |

#### `VIDEO`

Notice about video metrics definition changes:

The `video_total_views` metric within the `VIDEO` metrics group reports on 100%-in view for at least 3 seconds and when a user manually clicks on the play button.

Our original video view definition of 100% in view for at least 3 seconds will continue to be available as a new `video_3s100pct_views` metric in the `VIDEO` metrics group. To continue to bid and be charged based on the original view definition, use the newly available `VIEW_3S_100PCT` bid\_unit.

|                        |                                                                                                            |                        |               |
| :--------------------- | :--------------------------------------------------------------------------------------------------------- | :--------------------- | :------------ |
| Metric                 | Description                                                                                                | Segmentation Available | Data Type     |
| `video_total_views`    | Total number of video views                                                                                | ✔                      | Array of ints |
| `video_views_25`       | Total number of views where at least 25% of the video was viewed.                                          | ✔                      | Array of ints |
| `video_views_50`       | Total number of views where at least 50% of the video was viewed.                                          | ✔                      | Array of ints |
| `video_views_75`       | Total number of views where at least 75% of the video was viewed.                                          | ✔                      | Array of ints |
| `video_views_100`      | Total number of views where at least 100% of the video was viewed.                                         | ✔                      | Array of ints |
| `video_cta_clicks`     | Total clicks on the call to action                                                                         | ✔                      | Array of ints |
| `video_content_starts` | Total number of video playback starts                                                                      | ✔                      | Array of ints |
| `video_3s100pct_views` | Total number of views where at least 3 seconds were played while 100% in view (legacy `video_total_views`) | ✔                      | Array of ints |
| `video_6s_views`       | Total number of views where at least 6 seconds of the video was viewed                                     | ✔                      | Array of ints |
| `video_15s_views`      | Total number of views where at least 15 seconds of the video or for 95% of the total duration was viewed   | ✔                      | Array of ints |

#### `WEB_CONVERSION`

|                                     |                                                                                                          |                                        |             |
| :---------------------------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------- | :---------- |
| Metric                              | Description                                                                                              | Segmentation Available                 | Data Type   |
| `conversion_purchases`              | Number of conversions of type PURCHASE and the corresponding sale amount and order quantity              | `PLATFORMS` only                       | JSON object |
| `conversion_sign_ups`               | Number of conversions of type SIGN\_UP and the corresponding sale amount and order quantity              | `PLATFORMS` only                       | JSON object |
| `conversion_site_visits`            | Number of conversions of type SITE\_VISIT and the corresponding sale amount and order quantity           | `PLATFORMS` only                       | JSON object |
| `conversion_downloads`              | Number of conversions of type DOWNLOAD and the corresponding sale amount and order quantity              | `PLATFORMS` only                       | JSON object |
| `conversion_custom`                 | Number of conversions of type CUSTOM and the corresponding sale amount and order quantity                | `PLATFORMS` only                       | JSON object |
| `conversion_add_to_carts`           | Number of conversions of type ADD TO CART and the corresponding sale amount and order quantity           | `PLATFORMS` and `CONVERSION_TAGS` only | JSON object |
| `conversion_checkouts_initiated`    | Number of conversions of type CHECKOUT INITIATED and the corresponding sale amount and order quantity    | `PLATFORMS` and `CONVERSION_TAGS` only | JSON object |
| `conversion_content_views`          | Number of conversions of type CONTENT VIEW and the corresponding sale amount and order quantity          | `PLATFORMS` and `CONVERSION_TAGS` only | JSON object |
| `conversion_payment_info_additions` | Number of conversions of type PAYMENT INFO ADDITION and the corresponding sale amount and order quantity | `PLATFORMS` and `CONVERSION_TAGS` only | JSON object |
| `conversion_add_to_wishlists`       | Number of conversions of type ADD TO WISHLIST and the corresponding sale amount and order quantity       | `PLATFORMS` and `CONVERSION_TAGS` only | JSON object |
| `conversion_searches`               | Number of conversions of type SEARCH and the corresponding sale amount and order quantity                | `PLATFORMS` and `CONVERSION_TAGS` only | JSON object |
| `conversion_landing_page_views`     | Number of conversions of type LANDING PAGE VIEWS and the corresponding sale amount and order quantity    | `PLATFORMS` and `CONVERSION_TAGS` only | JSON object |
| `conversion_subscriptions`          | Number of conversions of type SUBSCRIPTIONS and the corresponding sale amount and order quantity         | `PLATFORMS` and `CONVERSION_TAGS` only | JSON object |

#### `MOBILE_CONVERSION`

Mobile conversion stats are available only to advertiser accounts enabled for MACT.

|                                            |                                                                                                                                              |                        |             |
| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------- | :---------- |
| Metric                                     | Description                                                                                                                                  | Segmentation Available | Data Type   |
| `mobile_conversion_spent_credits`          | Breakdown of mobile conversions of type SPENT\_CREDIT by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount           | ✔                      | JSON object |
| `mobile_conversion_installs`               | Breakdown of mobile conversions of type INSTALL by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount                 | ✔                      | JSON object |
| `mobile_conversion_content_views`          | Breakdown of mobile conversions of type CONTENT\_VIEW by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount           | ✔                      | JSON object |
| `mobile_conversion_add_to_wishlists`       | Breakdown of mobile conversions of type ADD\_TO\_WISHLIST by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount       | ✔                      | JSON object |
| `mobile_conversion_checkouts_initiated`    | Breakdown of mobile conversions of type CHECKOUT\_INITIATED by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount     | ✔                      | JSON object |
| `mobile_conversion_reservations`           | Breakdown of mobile conversions of type RESERVATION by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount             | ✔                      | JSON object |
| `mobile_conversion_tutorials_completed`    | Breakdown of mobile conversions of type TUTORIAL\_COMPLETED by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount     | ✔                      | JSON object |
| `mobile_conversion_achievements_unlocked`  | Breakdown of mobile conversions of type ACHIEVEMENT\_UNLOCKED by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount   | ✔                      | JSON object |
| `mobile_conversion_searches`               | Breakdown of mobile conversions of type SEARCH by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount                  | ✔                      | JSON object |
| `mobile_conversion_add_to_carts`           | Breakdown of mobile conversions of type ADD\_TO\_CART by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount           | ✔                      | JSON object |
| `mobile_conversion_payment_info_additions` | Breakdown of mobile conversions of type PAYMENT\_INFO\_ADDITION by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount | ✔                      | JSON object |
| `mobile_conversion_re_engages`             | Breakdown of mobile conversions of type RE\_ENGAGE by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount              | ✔                      | JSON object |
| `mobile_conversion_shares`                 | Breakdown of mobile conversions of type SHARE by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount                   | ✔                      | JSON object |
| `mobile_conversion_rates`                  | Breakdown of mobile conversions of type RATE by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount                    | ✔                      | JSON object |
| `mobile_conversion_logins`                 | Breakdown of mobile conversions of type LOGIN by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount                   | ✔                      | JSON object |
| `mobile_conversion_updates`                | Breakdown of mobile conversions of type UPDATE by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount                  | ✔                      | JSON object |
| `mobile_conversion_levels_achieved`        | Breakdown of mobile conversions of type LEVEL\_ACHIEVED by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount         | ✔                      | JSON object |
| `mobile_conversion_invites`                | Breakdown of mobile conversions of type INVITE by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount                  | ✔                      | JSON object |
| `mobile_conversion_key_page_views`         | Breakdown of mobile conversions of type KEY\_PAGE\_VIEW by post\_view and post\_engagement                                                   | ✔                      | JSON object |
| mobile\_conversion\_downloads              | Breakdown of mobile conversions of type DOWNLOAD by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount                | ✔                      | JSON object |
| mobile\_conversion\_purchases              | Breakdown of mobile conversions of type PURCHASE by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount                | ✔                      | JSON object |
| mobile\_conversion\_sign\_ups              | Breakdown of mobile conversions of type SIGN\_UP by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount                | ✔                      | JSON object |
| mobile\_conversion\_site\_visits           | Breakdown of mobile conversions of type SITE\_VISIT by post\_view, post\_engagement, assisted, order\_quantity, and sale\_amount             | ✔                      | JSON object |

#### `LIFE_TIME_VALUE_MOBILE_CONVERSION`

Lifetime mobile conversion stats are available only to advertiser accounts enabled for MACT.

|                                                           |                                                                 |                        |             |
| :-------------------------------------------------------- | :-------------------------------------------------------------- | :--------------------- | :---------- |
| Metric                                                    | Description                                                     | Segmentation Available | Data Type   |
| `mobile_conversion_lifetime_value_purchases`              | Breakdown of mobile conversions of type PURCHASE                |                        | JSON object |
| `mobile_conversion_lifetime_value_sign_ups`               | Breakdown of mobile conversions of type SIGN\_UP                |                        | JSON object |
| `mobile_conversion_lifetime_value_updates`                | Breakdown of mobile conversions of type UPDATE                  |                        | JSON object |
| `mobile_conversion_lifetime_value_tutorials_completed`    | Breakdown of mobile conversions of type TUTORIAL\_COMPLETED     |                        | JSON object |
| `mobile_conversion_lifetime_value_reservations`           | Breakdown of mobile conversions of type RESERVATION             |                        | JSON object |
| `mobile_conversion_lifetime_value_add_to_carts`           | Breakdown of mobile conversions of type ADD\_TO\_CART           |                        | JSON object |
| `mobile_conversion_lifetime_value_add_to_wishlists`       | Breakdown of mobile conversions of type ADD\_TO\_WISHLIST       |                        | JSON object |
| `mobile_conversion_lifetime_value_checkouts_initiated`    | Breakdown of mobile conversions of type CHECKOUT\_INITIATED     |                        | JSON object |
| `mobile_conversion_lifetime_value_levels_achieved`        | Breakdown of mobile conversions of type LEVEL\_ACHIEVED         |                        | JSON object |
| `mobile_conversion_lifetime_value_achievements_unlocked`  | Breakdown of mobile conversions of type ACHIEVEMENT\_UNLOCKED   |                        | JSON object |
| `mobile_conversion_lifetime_value_shares`                 | Breakdown of mobile conversions of type SHARE                   |                        | JSON object |
| `mobile_conversion_lifetime_value_invites`                | Breakdown of mobile conversions of type INVITE                  |                        | JSON object |
| `mobile_conversion_lifetime_value_payment_info_additions` | Breakdown of mobile conversions of type PAYMENT\_INFO\_ADDITION |                        | JSON object |
| `mobile_conversion_lifetime_value_spent_credits`          | Breakdown of mobile conversions of type SPENT\_CREDIT           |                        | JSON object |
| `mobile_conversion_lifetime_value_rates`                  | Breakdown of mobile conversions of type RATE                    |                        | JSON object |

### Segmentation

Segmentation reporting allows the retrieval of metrics broken out by the values of a given targeting type. Segmentation is only available through [asynchronous analytics queries](/x-ads-api/analytics#asynchronous-analytics) due to their significant added complexity.

As of May 2026, only the following segmentation types are enabled. METROS returns Nielsen DMA codes as numeric strings (819 = Seattle-Tacoma). Geographic segmentation types such as METROS require the country parameter (96683cc9126741d1 for US).

|                    |                          |
| :----------------- | :----------------------- |
| Segmentation Type  | `country` param required |
| `AGE`              |                          |
| `GENDER`           |                          |
| `METROS`           | ✔                        |
| `PLATFORMS`        |                          |
| `CONVERSION_TAGS*` |                          |

\*The CONVERSION\_TAGS segmentation is only compatible with the WEB\_CONVERSION metric group.

## Derived Metrics

Campaign metrics depend on their [campaign objective](/x-ads-api/campaign-management). Use this guide to determine how to calculate derived metrics for use based on the objectives in place.

Any `metric` without curly brackets is one that is returned by the Ads API [analytics](/x-ads-api/analytics#synchronous-analytics) endpoints. Any name surrounded by `{curly brackets}` indicates a derived metric for that category.

### ENGAGEMENTS

|                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| :------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Derived Metric                                                                                                 | Exposed Metric Calculation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `billed_charge_local_micro / {Impressions} / 1000`                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `{Total Engagements}`                                                                                          | `promoted_account_follows + promoted_tweet_search_engagements + promoted_tweet_timeline_engagements + promoted_tweet_profile_engagements` or `promoted_account_follows + promoted_tweet_search_clicks + promoted_tweet_search_replies + promoted_tweet_search_retweets + promoted_tweet_search_follows + promoted_tweet_timeline_clicks + promoted_tweet_timeline_replies + promoted_tweet_timeline_retweets + promoted_tweet_timeline_follows + promoted_tweet_profile_clicks + promoted_tweet_profile_replies + promoted_tweet_profile_retweets + promoted_tweet_profile_follows` |
| `{Engagement Rate}`                                                                                            | `{Total Engagements} / {Impressions}`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `billed_charge_local_micro / {Total Engagements}`                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

### WEBSITE\_CLICKS

|                                                                                                                |                                                                                                             |
| :------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
| Derived Metric                                                                                                 | Exposed Metric Calculation                                                                                  |
| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |                                                                                                             |
| `billed_charge_local_micro / {Impressions} / 1000`                                                             |                                                                                                             |
| `{Link Clicks}`                                                                                                | `promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks` |
| `{Click Rate}`                                                                                                 | `{Link Clicks} / {Impressions}`                                                                             |
| `billed_charge_local_micro / {Link Clicks}`                                                                    |                                                                                                             |
| `conversion_site_visits`                                                                                       |                                                                                                             |
| `{Conversion Rate}`                                                                                            | `conversion_site_visits / {Impressions}`                                                                    |
| `billed_charge_local_micro / conversion_site_visits`                                                           |                                                                                                             |

### APP\_INSTALLS

|                                                                           |                                                                                                                                                  |
| :------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| Derived Metric                                                            | Exposed Metric Calculation                                                                                                                       |
| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions` |                                                                                                                                                  |
| `billed_charge_local_micro / {Impressions} / 1000`                        |                                                                                                                                                  |
| `{App Clicks}`                                                            | `promoted_tweet_app_install_attempts + promoted_tweet_app_open_attempts + promoted_tweet_timeline_url_clicks + promoted_tweet_search_url_clicks` |
| `{App Click Rate}`                                                        | `{App Clicks} / {Impressions}`                                                                                                                   |
| `billed_charge_local_micro / {App Clicks}`                                |                                                                                                                                                  |
| `billed_charge_local_micro / mobile_conversion_installs`                  |                                                                                                                                                  |

### FOLLOWERS

|                                                        |                                |
| :----------------------------------------------------- | :----------------------------- |
| Derived Metric                                         | Exposed Metric Calculation     |
| `promoted_account_impressions`                         |                                |
| `billed_charge_local_micro / {Impressions} / 1000`     |                                |
| `promoted_account_follows`                             |                                |
| `{Follow Rate}`                                        | `promoted_account_follow_rate` |
| `billed_charge_local_micro / promoted_account_follows` |                                |

### VIDEO\_VIEWS

|                                                                                                                |                                                          |
| :------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------- |
| Derived Metric                                                                                                 | Exposed Metric Calculation                               |
| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |                                                          |
|                                                                                                                | `billed_charge_local_micro / {Impressions} / 1000`       |
| `{Video Views}`                                                                                                | `promoted_video_total_views`                             |
| `{Video Rate}`                                                                                                 | `promoted_video_total_views / {Impressions}`             |
| `{Cost Per View}`                                                                                              | `billed_charge_local_micro / promoted_video_total_views` |

### QUALIFIED\_IMPRESSIONS

|                                                                                                                |                                                                                                                                              |
| :------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| Derived Metric                                                                                                 | Exposed Metric Calculation                                                                                                                   |
| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |                                                                                                                                              |
|                                                                                                                | `billed_charge_local_micro / {Impressions} / 1000`                                                                                           |
| `{Qualified Impressions}`                                                                                      | `promoted_tweet_timeline_qualified_impressions + promoted_tweet_search_qualified_impressions + promoted_tweet_profile_qualified_impressions` |
| `{Qualified Impression Rate}`                                                                                  | `{Qualified Impressions} / {Impressions}`                                                                                                    |
| `{Cost Per 1000 Qualified Impressions }`                                                                       | `billed_charge_local_micro / {Qualified Impressions} / 1000`                                                                                 |

### CUSTOM

For `placement_type` of `PROMOTED_ACCOUNT` see the `FOLLOWERS` objective above. For all other placements with this objective, see `ENGAGEMENTS` for the corresponding derived metrics.

## Guides

### Active Entities

#### Introduction

The [Active Entities endpoint](/x-ads-api/analytics#get-stats-accounts-account-id-active-entities) is designed to be used in conjunction with our [synchronous](/x-ads-api/analytics#get-stats-accounts-account-id) and [asynchronous](/x-ads-api/analytics#asynchronous-analytics) analytics endpoints as it provides information about which campaigns to request analytics for. It does this by returning details about ads entities and when their metrics changed. Using this endpoint will greatly simplify your code and analytics fetching logic.

This guide includes information and context about the endpoint and its data source. It also provides [usage guidelines](#usage) and a series of [example requests](#example), demonstrating how to use Active Entities in conjunction with our analytics endpoints. The [Summary section](#summary) provides a high-level description of the recommended approach.

#### Data

Whenever an ads entity metric changes, we record information about that change. These change events are stored in hourly buckets and include details about the entity as well as the time that the change applies to. The latter is necessary because change events do not always correspond to when they were recorded. Billing adjustments are a common reason for this, but there are others, too.

#### Endpoint

### Request

Active Entities requests are scoped under ads accounts and have three required query parameters: `entity`, `start_time`, and `end_time`.

`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2026-03-05T00:00:00Z&end_time=2026-03-06T00:00:00Z"`

The following `entity` values are supported: `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `PROMOTED_ACCOUNT`, and `PROMOTED_TWEET`. This reflects the entity types that our analytics endpoints support.

The `start_time` and `end_time` values must be expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) and specify which hourly buckets to query. These must be expressed in whole hours.

This endpoint also supports three optional parameters that can be used to filter results: `funding_instrument_ids`, `campaign_ids`, and `line_item_ids`. These work at all levels of the ads hierarchy and with any specified `entity` type.

### Response

The Active Entities response for the request above is shown below.

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "PROMOTED_TWEET",
          "start_time": "2026-03-05T00:00:00Z",
          "end_time": "2026-03-06T00:00:00Z"
        }
      },
      "data": [
        {
          "entity_id": "2r0wxw",
          "activity_start_time": "2026-03-04T20:55:20Z",
          "activity_end_time": "2026-03-05T03:43:56Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        },
        {
          "entity_id": "2r30fn",
          "activity_start_time": "2026-03-05T08:11:08Z",
          "activity_end_time": "2026-03-05T14:40:59Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        }
      ]
    }
```

The `data` array includes an object for every entity that should be included in a subsequent analytics request. You should not request analytics for IDs outside of this set.

Each object includes four fields: `entity_id`, `activity_start_time`, `activity_end_time`, and `placements`. The activity start and end times represent the time range that the associated entity's change events apply to and, thus, determine the dates that should be specified in subsequent analytics requests. The `placements` array can include the following values: `ALL_ON_TWITTER`, `SPOTLIGHT`, and `TREND`. It indicates which placements should be requested for the given entity ID.

#### Usage

The Active Entities endpoint should dictate how analytics requests are made. The following usage guidelines are written to support analytics synchronization, enabling partners to keep their data stores in sync with X. In other words, it describes how to perform regularly-scheduled background syncs.

There are two decisions a developer must make.

1. How often to request active entities information and, thus, how often to pull analytics.
2. How to use the activity start and end times to determine the analytics request's `start_time` and `end_time` values.

These are discussed in greater detail in each of the two subsections, below, after the summary.

### Summary

Use the Active Entities endpoint in the following way to dictate how analytics requests are made. Follow this after you've decided how often to request active entities information and, thus, how often to pull analytics.

1. Make the Active Entities request.
2. Split the response by placement. One group for `ALL_ON_TWITTER`, one for `SPOTLIGHT`, and one for `TREND`.
3. For each placement group, do the following.
   1. Extract the entity IDs.
   2. Determine the analytics `start_time` and `end_time` values.
      * Find the minimum `activity_start_time`. Round this value down.
      * Find the maximum `activity_end_time`. Round this value up.
   3. Make the analytics request(s).
      * Group entity IDs into batches of 20.
      * Use the `start_time` and `end_time` values from #3b.
      * Specify the appropriate `placement` value.
   4. Write to your data store.

Please see [active\_entities.py](https://github.com/xdevplatform/twitter-python-ads-sdk/blob/master/examples/active_entities.py) as an example that uses the Python SDK.

### Frequency

The answer to the first question determines the time range that should be used in Active Entities requests. For example, if requesting active entities information every hour, the time range should be an hour. If requesting active entities information once a day, the time range should be a day. In other words, time ranges should be selected such that the current request's `start_time` is equal to the previous request's `end_time`.

<Note>
  **Note**: A time window should only be requested once. Requesting a time window more than once will lead to unnecessary analytics requests. (Exception below.)
</Note>

For partners wishing to request analytics multiple times an hour for the *current* hour, the same pattern applies—the frequency determines the time range. The table below shows example Active Entities start and end timestamps for this scenario.

|                  |                            |                          |
| :--------------- | :------------------------- | :----------------------- |
| **Request time** | **`start_time` timestamp** | **`end_time` timestamp** |
| 00:15:00         | 00:00:00                   | 00:15:00                 |
| 00:30:00         | 00:15:00                   | 00:30:00                 |
| 00:45:00         | 00:30:00                   | 00:45:00                 |
| 01:00:00         | 00:45:00                   | 01:00:00                 |

Given the way that change events are stored, all four Active Entities requests above query the same hourly bucket, which is necessary for this use case. However, after the current hour, this hourly bucket should no longer be queried.

### Activity Times

We recommend the following approach to working with activity start and end times. Across all objects in the Active Entities response, find the minimum `activity_start_time` and the maximum `activity_end_time`. Modify these values by rounding the minimum activity start time down and rounding the maximum activity end time up. Specifically, set the timestamps to zero for both and add one day to the end time, as illustrated in the following table. These are the start and end times that should be specified in subsequent analytics requests.

|                                                        |                                                        |
| :----------------------------------------------------- | :----------------------------------------------------- |
| **Min, max activity times**                            | **Derived times**                                      |
| 2026-03-04T20:55:20Z  <br /><br />2026-03-05T14:40:59Z | 2026-03-04T00:00:00Z  <br /><br />2026-03-06T00:00:00Z |

**Note**: It's important to include the timestamps with hours, minutes, and seconds set to zero. Otherwise, if only the date is passed in, we will assume you're requesting analytics starting and ending at midnight in the ads account's timezone, which may not be desirable. For example, if the minimum activity start time is 2026-02-28T01:30:07Z and the timestamp is omitted for an ads account with an offset of -08:00:00, the analytics request will miss changes that happened between 01:30 and 08:00.

Alternatively, if you would prefer to request analytics for just the returned activity time window without expanding to full days, you can. Using this approach, the derived start and end times would be 2026-03-04T20:00:00Z and 2026-03-05T15:00:00Z, respectively. (Note that ranges like these are not accepted if you specify `DAY` granularity in the analytics request.)

#### Example

This section demonstrates how to use Active Entities in conjunction with the synchronous analytics endpoint. (The responses have been slightly modified for readability.) In this example, the Active Entities endpoint is called at the top of each hour, with each request looking at the previous hour. The response determines how the synchronous analytics endpoint is used.

The first Active Entities request is made at 03:00:00. The response indicates that line item dvcz7's metrics changed and that those change events apply to the window between 02:02:55 and 02:28:12.

```text theme={null}
`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T02:00:00Z&end_time=2026-02-11T03:00:00Z"`
```

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2026-02-11T02:02:55Z",
          "activity_end_time": "2026-02-11T02:58:12Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }
```

Based on these activity start and end times and using the approach described above, the analytics `start_time` and `end_time` values are set to 2026-02-11T00:00:00Z and 2026-02-12T00:00:00Z, respectively. We see that the third element in each of the metrics arrays below are non-zero, as we expected based on the active entities information.

```text theme={null}
`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2026-02-11T00:00:00Z&end_time=2026-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2792,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,60,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1326,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }
```

The next Active Entities request happens at 04:00:00 and only looks at the previous hour. As mentioned above, a time window should only be requested once. Based on the response, we see that change events for this line item apply to *both* 02:00:00 and 03:00:00. In the subsequent analytics request, we expect to see changes for both hours.

```text theme={null}
`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T03:00:00Z&end_time=2026-02-11T04:00:00Z"`
```

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2026-02-11T02:07:17Z",
          "activity_end_time": "2026-02-11T03:49:22Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }
```

In addition to seeing non-zero metrics for 03:00:00, we see that the impressions, spend, and MRC video views have been updated from their previous values. Impressions, for example, are now 2,995 for the 02:00:00 hour, up from 2,792. This demonstrates how change events that were recorded during the 03:00:00 hour apply to the 02:00:00 hour.

```text theme={null}
`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2026-02-11T00:00:00Z&end_time=2026-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2995,734,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,65,7,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1449,342,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }
```

The Active Entities request at 05:00:00, again looking at just the previous hour, shows that change events apply to the 03:00:00 hour only. The changes to analytics metrics in the subsequent request reflect this.

```text theme={null}
`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T04:00:00Z&end_time=2026-02-11T05:00:00Z"`
```

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2026-02-11T03:42:39Z",
          "activity_end_time": "2026-02-11T03:48:48Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }
```

The analytics response shows that only metrics for the 03:00:00 hour have changed; the values for the 02:00:00 hour are the same as they were during the previous analytics request.

```text theme={null}
`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2026-02-11T00:00:00Z&end_time=2026-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2995,753,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,65,8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1449,351,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }
```

Finally, at 06:00:00 we see that there are no additional change events. **Note**: This does *not* imply that metrics for this line item cannot change in the future, though.

```text theme={null}
`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T05:00:00Z&end_time=2026-02-11T06:00:00Z"`
```

```json theme={null}
    {
      "request": {},
      "data": []
    }
```

### Asynchronous Guide

## API Reference

### Asynchronous Analytics

#### Introduction

The asynchronous analytics endpoints allow partners and advertisers to request metrics by submitting create requests that the server processes asynchronously. (We refer to these as asynchronous analytics "jobs.") With this approach, the client's connection does not need to remain open until the request has been fulfilled.

These endpoints, like their synchronous counterpart, allow partners and advertisers to request detailed statistics on campaign performance. They support requesting data for accounts, funding instruments, campaigns, line items, promoted posts, and media creatives. The difference between these and the synchronous endpoint is that the asynchronous analytics endpoints support longer date ranges, up to 90 days, as well as segmentation. Additional details on the differences between the two can be found on our [Analytics Overview](/x-ads-api/analytics) page.

Unlike our synchronous endpoints, rate limiting is based on the number of concurrent jobs for a given account. In other words, it's based on the number of jobs that can be in a processing state at a given time. We count this at the ads account level.

#### Usage

Retrieving campaign metrics using the asynchronous analytics endpoints is a multi-step process. It involves creating a job, checking whether the job has finished processing, and, finally, downloading the data. The data file must be decompressed. The four specific steps are outlined below.

1. Create the job using the [POST stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics) endpoint.
2. Make requests at regular intervals to the [GET stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics) endpoint to determine whether the job has finished processing.
3. Once the job has finished processing, download the data file.
4. Unzip the data file.

The response object returned in the data file has the same JSON schema as the synchronous analytics endpoint's response.

Segmented campaign metrics are only available via the asynchronous analytics endpoints. Campaign metrics can be broken out by location, gender, interest, keyword, and more. For a full list of options, see the [Metrics and Segmentation](/x-ads-api/analytics#metrics-and-segmentation) page. In order to request segmented metrics, use the `segmentation_type` request parameter when creating the job.

#### Example

This section demonstrates how to use the asynchronous analytics endpoints.

Start by creating a job using the [POST stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics) endpoint. The example below requests engagement metrics—such as impressions, likes, clicks, etc.—for a specific line item over a week's time. (Note that the requested time range goes up to, but does not include March 20th since the timestamp is set to midnight.)

```text theme={null}
$ twurl -X POST -H ads-api.x.com "/12/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=el32n&start_time=2026-03-12T00:00:00Z&end_time=2026-03-20T00:00:00Z&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT"
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "start_time": "2026-03-12T00:00:00Z",
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2026-03-20T00:00:00Z",
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      },
      "data": {
        "start_time": "2026-03-12T00:00:00Z",
        "segmentation_type": null,
        "url": null,
        "id_str": "1120829647711653888",
        "entity_ids": [
          "el32n"
        ],
        "end_time": "2026-03-20T00:00:00Z",
        "country": null,
        "placement": "ALL_ON_TWITTER",
        "id": 1120829647711653888,
        "expires_at": null,
        "account_id": "18ce54d4x5t",
        "status": "PROCESSING",
        "granularity": "TOTAL",
        "entity": "LINE_ITEM",
        "created_at": "2026-04-01T23:19:46Z",
        "platform": null,
        "updated_at": "2026-04-01T23:19:46Z",
        "metric_groups": [
          "ENGAGEMENT"
        ]
      }
    }
```

This response does not return the line item metrics. It simply provides information about the job you just created. The job ID is needed to check on the status of the job. This is shown in both the `id` and `id_str` response attributes.

Next, you'll want to check whether the job you've created using the `id_str` from the previous response, has finished processing as indicated by `"status": "SUCCESS"` in the response. This means the data is ready to download. The `url` field contains the download link.

```text theme={null}
$ twurl -H ads-api.x.com "/12/stats/jobs/accounts/18ce54d4x5t?job_ids=1120829647711653888"
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "job_ids": [
            1120829647711653888
          ]
        }
      },
      "next_cursor": "1120828505715920896",
      "data": [
        {
          "start_time": "2026-03-12T00:00:00Z",
          "segmentation_type": null,
          "url": "https://ton.twimg.com/advertiser-api-async-analytics/stats_job_1120829647711653888.json.gz",
          "id_str": "1120829647711653888",
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2026-03-20T00:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "id": 1120829647711653888,
          "expires_at": "2026-04-03T23:19:48Z",
          "account_id": "18ce54d4x5t",
          "status": "SUCCESS",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "created_at": "2026-04-01T23:19:46Z",
          "platform": null,
          "updated_at": "2026-04-01T23:19:48Z",
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      ]
    }
```

While we're passing in a single job ID in the above example, in practice, you'll want to use the `job_ids` parameter to check on the status of multiple jobs at a time by specifying up to 200 job IDs.

Next, download the data file using the listed `url` value.

```text theme={null}
    $ wget https://ton.twimg.com/advertiser-api-async-analytics/stats_job_1120829647711653888.json.gz
```

Finally, unzip the data file.

```text theme={null}
`$ gunzip stats_job_1120829647711653888.json.gz`
```

The contents of the file are shown below.

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "data_type": "stats",
      "time_series_length": 1,
      "data": [
        {
          "id": "el32n",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  3482
                ],
                "tweets_send": null,
                "qualified_impressions": null,
                "follows": null,
                "app_clicks": null,
                "retweets": [
                  102
                ],
                "unfollows": null,
                "likes": [
                  15
                ],
                "engagements": [
                  171
                ],
                "clicks": [
                  30
                ],
                "card_engagements": null,
                "poll_card_vote": null,
                "replies": null,
                "carousel_swipes": null
              }
            }
          ]
        }
      ],
      "request": {
        "params": {
          "start_time": "2026-03-12T00:00:00Z",
          "segmentation_type": null,
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2026-03-20T00:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "platform": null,
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      }
    }
```

### Reach and Average Frequency

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET stats/accounts/:account\_id/reach/campaigns

Retrieve reach and average frequency analytics for specified campaigns.

### Resource URL

`https://ads-api.x.com/stats/accounts/:account_id/reach/campaigns`

### Parameters

| Name                            | Description                                                                                                                                                                                                                                                                                                                                                     |
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id  <br />*required*   | The identifier 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.<br /><br />Type: string<br /><br />Example: `18ce54d4x5t` |
| campaign\_ids  <br />*required* | Scope the response to just the desired campaigns by specifying a comma-separated list of identifiers. Up to 20 IDs may be provided.<br /><br />**Note**: Up to 20 campaign IDs may be provided.<br /><br />Type: string<br /><br />Example: `8fgzf`                                                                                                             |
| end\_time  <br />*required*     | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).<br /><br />Type: string<br /><br />Example: `2026-05-26T07:00:00Z`                                                                                       |
| start\_time  <br />*required*   | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).<br /><br />Type: string<br /><br />Example: `2026-05-19T07:00:00Z`                                                                                     |

### Example Request

`GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/campaigns?campaign_ids=8fgzf&start_time=2026-05-19&end_time=2026-05-26`

### Example Response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "campaign_ids": [
            "8fgzf"
          ],
          "start_time": "2026-05-19T00:00:00Z",
          "end_time": "2026-05-26T00:00:00Z",
          "account_id": "18ce54d4x5t"
        }
      },
      "data_type": "reach",
      "data": [
        {
          "id": "8fgzf",
          "total_audience_reach": 1217,
          "average_frequency": 1.01
        }
      ]
    }
```

#### GET stats/accounts/:account\_id/reach/funding\_instruments

Retrieve reach and average frequency analytics for specified funding instruments.

### Resource URL

`https://ads-api.x.com/stats/accounts/:account_id/reach/funding_instruments`

### Parameters

| Name                                       | Description                                                                                                                                                                                                                                                                                                                                                     |
| :----------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id  <br />*required*              | The identifier 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.<br /><br />Type: string<br /><br />Example: `18ce54d4x5t` |
| funding\_instrument\_ids  <br />*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.<br /><br />**Note**: Up to 20 funding instrument IDs may be provided.<br /><br />Type: string<br /><br />Example: `lygyi`                                                                                         |
| end\_time  <br />*required*                | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).<br /><br />Type: string<br /><br />Example: `2026-05-26T07:00:00Z`                                                                                       |
| start\_time  <br />*required*              | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).<br /><br />Type: string<br /><br />Example: `2026-05-19T07:00:00Z`                                                                                     |

### Example Request

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

### Example Response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "funding_instrument_ids": [
            "lygyi"
          ],
          "start_time": "2026-05-19T00:00:00Z",
          "end_time": "2026-05-26T00:00:00Z",
          "account_id": "18ce54d4x5t"
        }
      },
      "data_type": "reach",
      "data": [
        {
          "id": "lygyi",
          "total_audience_reach": 1217,
          "average_frequency": 1.01
        }
      ]
    }
```

### Synchronous Analytics

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET stats/accounts/:account\_id

Retrieve synchronous analytics for the current account. A maximum time range (`end_time` - `start_time`) of 7 days is allowed.

### Resource URL

`https://ads-api.x.com/12/stats/accounts/:account_id`

### Parameters

| Name                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id  <br />*required*    | The identifier 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.<br /><br />Type: string<br /><br />Example: `18ce54d4x5t`                                                                                 |
| end\_time  <br />*required*      | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).<br /><br />Type: string<br /><br />Example: `2026-05-26T07:00:00Z`                                                                                                                                                                       |
| entity  <br />*required*         | The entity type to retrieve data for.<br /><br />Type: enum<br /><br />Possible values: `ACCOUNT`, `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET`                                                                                                                                                                                                                                                          |
| entity\_ids  <br />*required*    | The specific entities to retrieve data for. Specify a comma-separated list of entity IDs.<br /><br />**Note**: Up to 20 entity IDs may be provided.<br /><br />Type: string<br /><br />Example: `8u94t`                                                                                                                                                                                                                                         |
| granularity  <br />*required*    | Specify how granular the retrieved data should be.<br /><br />Type: enum<br /><br />Possible values: `DAY`, `HOUR`, `TOTAL`                                                                                                                                                                                                                                                                                                                     |
| metric\_groups  <br />*required* | The specific metrics that should be returned. Specify a comma-separated list of metric groups. For more information see [Metrics and Segmentation](/x-ads-api/analytics#metrics-and-segmentation).<br /><br />**Note**: `MOBILE_CONVERSION` data should be requested separately.<br /><br />Type: enum<br /><br />Possible values: `BILLING`, `ENGAGEMENT`, `LIFE_TIME_VALUE_MOBILE_CONVERSION`, `MOBILE_CONVERSION`, `VIDEO`, `WEB_CONVERSION` |
| placement  <br />*required*      | Scopes the retrieved data to a particular placement.<br /><br />**Note**: Only a single value accepted per request. For entities with both X and X Audience Platform placement, separate requests are required, one for each placement value.<br /><br />Type: enum<br /><br />Possible values: `ALL_ON_TWITTER`, `SPOTLIGHT`, `TREND`                                                                                                          |
| start\_time  <br />*required*    | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).<br /><br />Type: string<br /><br />Example: `2026-05-19T07:00:00Z`                                                                                                                                                                     |

### Example Request

```text theme={null}
GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=8u94t&start_time=2026-05-19&end_time=2026-05-26&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT
```

### Example Response

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "data_type": "stats",
      "time_series_length": 1,
      "data": [
        {
          "id": "8u94t",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  1233
                ],
                "tweets_send": null,
                "qualified_impressions": null,
                "follows": null,
                "app_clicks": null,
                "retweets": null,
                "likes": [
                  1
                ],
                "engagements": [
                  58
                ],
                "clicks": [
                  58
                ],
                "card_engagements": null,
                "poll_card_vote": null,
                "replies": null,
                "carousel_swipes": null
              }
            }
          ]
        }
      ],
      "request": {
        "params": {
          "start_time": "2026-05-19T07:00:00Z",
          "segmentation_type": null,
          "entity_ids": [
            "8u94t"
          ],
          "end_time": "2026-05-26T07:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "platform": null,
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      }
    }
```

### Active Entities

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET stats/accounts/:account\_id/active\_entities

Retrieve details about which entities' analytics metrics have changed in a given time period.

This endpoint should be used in conjunction with our analytics endpoints. The results of this endpoint indicate which ads entities to request analytics for. See our [Active Entities Guide](/x-ads-api/analytics#active-entities) for usage guidelines.

Change events are available in hourly buckets.

* The `start_time` and `end_time` values specify which hourly buckets to query.
* The returned `data` array will include an object for every entity that should be included in subsequent analytics requests.
* **IMPORTANT**: The dates that should be specified in subsequent analytics requests should be determined based on the `activity_start_time` and `activity_end_time` values.
  * These values represent the time ranges that the stored change events *apply to*. This is returned per entity.

|                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| :------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Derived Metric                                                                                                 | Exposed Metric Calculation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `billed_charge_local_micro / {Impressions} / 1000`                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `{Total Engagements}`                                                                                          | `promoted_account_follows + promoted_tweet_search_engagements + promoted_tweet_timeline_engagements + promoted_tweet_profile_engagements` or `promoted_account_follows + promoted_tweet_search_clicks + promoted_tweet_search_replies + promoted_tweet_search_retweets + promoted_tweet_search_follows + promoted_tweet_timeline_clicks + promoted_tweet_timeline_replies + promoted_tweet_timeline_retweets + promoted_tweet_timeline_follows + promoted_tweet_profile_clicks + promoted_tweet_profile_replies + promoted_tweet_profile_retweets + promoted_tweet_profile_follows` |
| `{Engagement Rate}`                                                                                            | `{Total Engagements} / {Impressions}`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `billed_charge_local_micro / {Total Engagements}`                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `{Media Views}`                                                                                                | `promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views`                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `{Media View Rate}`                                                                                            | `{Media Views} / {Impressions}`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

|                                                                                                                |                                                                                                             |
| :------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
| Derived Metric                                                                                                 | Exposed Metric Calculation                                                                                  |
| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |                                                                                                             |
| `billed_charge_local_micro / {Impressions} / 1000`                                                             |                                                                                                             |
| `{Link Clicks}`                                                                                                | `promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks` |
| `{Click Rate}`                                                                                                 | `{Link Clicks} / {Impressions}`                                                                             |
| `billed_charge_local_micro / {Link Clicks}`                                                                    |                                                                                                             |
| `conversion_site_visits`                                                                                       |                                                                                                             |
| `{Conversion Rate}`                                                                                            | `conversion_site_visits / {Impressions}`                                                                    |
| `billed_charge_local_micro / conversion_site_visits`                                                           |                                                                                                             |

|                                                                           |                                                                                                                                                  |
| :------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| Derived Metric                                                            | Exposed Metric Calculation                                                                                                                       |
| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions` |                                                                                                                                                  |
| `billed_charge_local_micro / {Impressions} / 1000`                        |                                                                                                                                                  |
| `{App Clicks}`                                                            | `promoted_tweet_app_install_attempts + promoted_tweet_app_open_attempts + promoted_tweet_timeline_url_clicks + promoted_tweet_search_url_clicks` |
| `{App Click Rate}`                                                        | `{App Clicks} / {Impressions}`                                                                                                                   |
| `billed_charge_local_micro / {App Clicks}`                                |                                                                                                                                                  |
| `billed_charge_local_micro / mobile_conversion_installs`                  |                                                                                                                                                  |

|                                                        |                                                                                                                |
| :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- |
| Derived Metric                                         | Exposed Metric Calculation                                                                                     |
| `promoted_account_impressions`                         |                                                                                                                |
| `billed_charge_local_micro / {Impressions} / 1000`     |                                                                                                                |
| `promoted_account_follows`                             |                                                                                                                |
| `{Follow Rate}`                                        | `promoted_account_follow_rate`                                                                                 |
| `billed_charge_local_micro / promoted_account_follows` |                                                                                                                |
| `{Media Views}`                                        | `promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views` |
| `{Media View Rate}`                                    | `{Media Views} / {Impressions}`                                                                                |

|                                                                                                                               |                                       |
| :---------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |
| Derived Metric                                                                                                                | Exposed Metric Calculation            |
| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions`                |                                       |
| `billed_charge_local_micro / {Impressions} / 1000`                                                                            |                                       |
| `promoted_tweet_search_card_engagements + promoted_tweet_timeline_card_engagements + promoted_tweet_profile_card_engagements` |                                       |
| `{Lead Rate}`                                                                                                                 | `{Leads} / {Impressions}`             |
| `{Cost Per Lead}`                                                                                                             | `billed_charge_local_micro / {Leads}` |

|                                                                                                                |                                                          |
| :------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------- |
| Derived Metric                                                                                                 | Exposed Metric Calculation                               |
| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |                                                          |
|                                                                                                                | `billed_charge_local_micro / {Impressions} / 1000`       |
| `{Video Views}`                                                                                                | `promoted_video_total_views`                             |
| `{Video Rate}`                                                                                                 | `promoted_video_total_views / {Impressions}`             |
| `{Cost Per View}`                                                                                              | `billed_charge_local_micro / promoted_video_total_views` |

|                                                                                                                |                                                                                                                                              |
| :------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| Derived Metric                                                                                                 | Exposed Metric Calculation                                                                                                                   |
| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |                                                                                                                                              |
|                                                                                                                | `billed_charge_local_micro / {Impressions} / 1000`                                                                                           |
| `{Qualified Impressions}`                                                                                      | `promoted_tweet_timeline_qualified_impressions + promoted_tweet_search_qualified_impressions + promoted_tweet_profile_qualified_impressions` |
| `{Qualified Impression Rate}`                                                                                  | `{Qualified Impressions} / {Impressions}`                                                                                                    |
| `{Cost Per 1000 Qualified Impressions }`                                                                       | `billed_charge_local_micro / {Qualified Impressions} / 1000`                                                                                 |

**Note**: A maximum time range (`end_time` - `start_time`) of 90 days is allowed.

### Resource URL

`https://ads-api.x.com/12/stats/accounts/:account_id/active_entities`

### Parameters

| Name                                       | Description                                                                                                                                                                                                                                                                                                                                                     |
| :----------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id  <br />*required*              | The identifier 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.<br /><br />Type: string<br /><br />Example: `18ce54d4x5t` |
| end\_time  <br />*required*                | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).<br /><br />Type: string<br /><br />Example: `2026-05-26T07:00:00Z`                                                                                       |
| entity  <br />*required*                   | The entity type to retrieve data for.<br /><br />Type: enum<br /><br />Possible values: `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET`                                                                                                                                                                                     |
| start\_time  <br />*required*              | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).<br /><br />Type: string<br /><br />Example: `2026-05-19T07:00:00Z`                                                                                     |
| campaign\_ids  <br />*optional*            | Scope the response to just entities associated with desired campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.<br /><br />**Note**: Exclusive with `funding_instrument_ids` and `line_item_ids`.<br /><br />Type: string<br /><br />Example: `8wku2`                                                                 |
| funding\_instrument\_ids  <br />*optional* | Scope the response to just entities associated with desired funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.<br /><br />**Note**: Exclusive with `campaign_ids` and `line_item_ids`.<br /><br />Type: string<br /><br />Example: `lygyi`                                                                 |
| line\_item\_ids  <br />*optional*          | Scope the response to just entities associated with desired line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.<br /><br />**Note**: Exclusive with `campaign_ids` and `line_item_ids`.<br /><br />Type: string<br /><br />Example: `8v7jo`                                                                          |

### Example Request

`GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2026-02-28&end_time=2026-03-01`

### Example Response

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "PROMOTED_TWEET",
          "start_time": "2026-02-28T08:00:00Z",
          "end_time": "2026-03-01T08:00:00Z"
        }
      },
      "data": [
        {
          "entity_id": "2mvb28",
          "activity_start_time": "2026-02-28T01:30:07Z",
          "activity_end_time": "2026-03-01T07:42:55Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        },
        {
          "entity_id": "2mvb29",
          "activity_start_time": "2026-02-27T11:30:07Z",
          "activity_end_time": "2026-03-01T07:42:50Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        },
        {
          "entity_id": "2mvfan",
          "activity_start_time": "2026-02-27T09:00:05Z",
          "activity_end_time": "2026-03-01T06:06:36Z",
          "placements": [
            "PUBLISHER_NETWORK"
          ]
        },
        {
          "entity_id": "2n17dx",
          "activity_start_time": "2026-02-28T02:02:26Z",
          "activity_end_time": "2026-03-01T07:52:44Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        }
      ]
    }
```


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

Overview of audience targeting on X Ads, covering Custom Audiences, CRM, web, mobile, and lookalike segments used to reach users in ad campaigns.

<BlueprintMark name="audiences" />

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

### Overview

There are multiple ways for partners to create [Custom Audiences](https://business.x.com/en/targeting/tailored-audiences.html).

* [Audience API (CRM)](#crm)
* [Web](#web)
* [Mobile](#mobile)
* [Flexible](#flexible)

Please note that you cannot exclude lookalike custom audiences from targeting. Additionally, you cannot target both a custom audience and a custom audience lookalike on the same ad line item (ad group).

**Audience management**

Audiences can be managed via audience partners and Ads API partners. We offer a series of endpoints in the API to access and maintain custom audiences.

For custom audience information, we offer 2 endpoints:

* [GET accounts/:account\_id/custom\_audiences](/x-ads-api/audiences)
* [GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id](/x-ads-api/audiences)

For more details on how to upload and manage audiences, view the [Audience API guide](/x-ads-api/audiences).

**Processing Times**

Generally speaking audience changes are processed in batches that run every 6-8 hours. While an audience change is processing the existing audience to be updated is unaffected. We do not recommend making more than one update for additions and one update for removals per audience within this timeframe.

**Targeting**

An audience can only be targeted if it matches at least 100 users active within the past 90 days on X-owned and -operated clients. [GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id](/x-ads-api/audiences) will indicate if an audience may not be targeted because it matches too few users.

**Audience API (CRM)**

<Frame>
  <img alt="image2" />
</Frame>

Audience or API partners provide a list of hashed identifiers and X performs a match and produces segments that are made available against media buying on X. Partners can create these audiences with the [Audience API](/x-ads-api/audiences).

**How it works?**

<Frame>
  <img alt="image3" />
</Frame>

**Web**

We offer a standard cookie matching process when working with MPP audience partners to identify segments to target against media buying on X. In addition, advertsiers can setup a [X Web Event Tag](/x-ads-api/measurement/web-conversions#web-event-tags) to collect website user data and create a corresponding Custom Audience.

**Setup Steps**

<Frame>
  <img alt="image0" />
</Frame>

**How it works?**

<Frame>
  <img alt="image1" />
</Frame>

**Mobile**

Please see [the Custom Audiences from Mobile Apps blog post](https://blog.x.com/2014/introducing-tailored-audiences-from-mobile-apps) for details.

**Flexible**

[Flexible audiences](/x-ads-api/audiences) give advertisers the ability to build and save audience combinations based on existing custom audiences or subsets of existing custom audiences. Subsets of a custom audience’s members can be targeted based on the recency and frequency of interaction.

**Restricted Use Cases for Custome Audiences**

[Read more about restrictions](https://developer.x.com/en/developer-terms/more-on-restricted-use-cases "Read more about restrictions")

### Audiences FAQ[](#real-time-tailored-audiences "Permalink to this headline")

**Q: We pushed a huge amount of data, why does the audience size show up as TOO\_SMALL?**

A: Currently the data is being added into audience in realtime, but the job which processes data to provide audience size will run only after a period of time. The correct audience size should be displayed in the UI after a matter of hours.

**Q: We finished sending audience data, and waited 24 hours or more, but still cannot target the audience - what should we do as next steps?**

A: Please confirm that the following things:

* The user ID being passed is correct and not malformed.
* The audience names being passed are correct and match previous membership updates.
* Please confirm the response from POST commands.
* Please confirm the ID Sync pixel is implemented correctly, and as described by ID Sync process enough users have visited the site in question to map users. Unmapped users in the membership updates will not be translated into targeted users.

If all else are confirmed as correct and working, please contact X product contacts with information as detailed as possible (see [Guide to Partner Inbounds](/x-ads-api/introduction) for example of preferred information).

**Q: How many times can we call the endpoint, and with what algorithm?**

A: We strongly recommend that you call our system with incremental deltas, and never re-send the complete audience memberships. The system has been tested to have a throughput sufficient to process incremental data updates for some of the largest websites in the world. The initial upload of audiences should be carefully throttled and first upload is expected to take a significant amount of time to complete.

**Q: What is the minimum size for an audience to be used for targeting?**

* The minimum size for an audience to is 100 users (post match). If an audience with less than 500 users is matched, it will not be available for targeting in the X Ads UI.

**Q: How long will it take to process the audience files? And how long will it take for the audience files to be ready in the X User Interface?**

* It typically takes 4-6 hours to process the audience files, but that will depend on the size of the file. Once the file is processed the audiences are available on the X Ads UI.

**Q: How is the match rate calculated?**

* Match Rate = 90 day active X users / number of users provided

**Q: How do we test if an audience file is working properly?**

* You can provide a test audience file and use “keltonlynn” as the advertiser handle. We can then verify that the file is able to be properly ingested and loaded into the X UI.

**Q: What is a partner user identifier (`p_user_id`)?**

* This is the identifier that is used by your company to uniquely identify each of your customers.

**Q: What is a standard ID?**

* This can be an email address, device ID, X @handle or ID).

**Q: How do I get the HMAC Key?**

* This will be provided by an encrypted email. Please provide your public PGP key to [mpp-inquiry@x.com](mailto:mpp-inquiry%x.com) and we will send you a test email to verify that everything is working. Once verified, we will send you the HMAC Key.

**Q: How do I verify that the hashing process worked using the given HMAC Key?**

* X will provide a test file (containing sample email addresses, device IDs, etc…) and a resulting hash file that you can verify your results against.

**Q: Is there a file size limitation for the full data match file?**

* No, there is no size limitation for the full data match file.

**Q: How long will it take for the full data match file to be processed?**

* Once the file is received by X, it will take approximately 1 day to process the file.

### CRM

<Frame>
  <img alt="image0" />
</Frame>

This document describes the integration details for Custom Audiences CRM partners including file formats & data exchange process.

**Summary**

Company will provide a list of hashed common user identifiers (i.e. e-mail addresses) or partner user IDs on behalf of a customer to X to perform a blind match and produce a list of X User IDs for targeting. The segments for targeting will be made available to the advertiser’s specific @handle specified by the filename in ads.x.com campaign setup.

All files from Company will be provided to X through a secure package on IronBox ([www.golockbox.com](http://www.golockbox.com)) through a specific account granted to Company by X. X will provide access to IronBox. Documentation on IronBox APIs can be found at [https://secure.goironcloud.com/Docs/Help/](https://secure.goironcloud.com/Docs/Help/).

#### Partner ID Matching Requirements

If company uses its own standard ID system to track users (i.e. not common user identifiers like email addresses, device ids, X user ID, etc...) then this is the recommended process.

**1. Full Data match**

Initially, Company will provide a comprehensive list of all user records which include a unique common user identifier with X in a single file to perform a full data match and produce a mapping stored by X of Partner IDs (`p_user_id`) to X IDs (`tw_id`). This will be done on a 2-3 month basis regularly to ensure proper upkeep. Once the match is completed, X will share a baseline match rate from this file with Company via e-mail.

The format of this file should be:

Name Convention: FullDataMatch.\[CompanyName].txt

Hashing Algorithm: HMAC\_SHA-256

Format:

Column 1: HMAC hashed value of common identifiers

Column 2: Partner User ID (unique per user, non-unique in file)

Column Delimiter (CSV): Commas will be used to delimit the hashed common user identifier from the Partner ID

Line separated values

* Ex: If user record A has Partner User ID 1 and common identifier 1, 2 and 3:

|                          |            |
| :----------------------- | :--------- |
| common user identifier 1 | p\_user\_1 |
| common user identifier 2 | p\_user\_1 |
| common user identifier 3 | p\_user\_1 |

\*See Hashing Directions section for common user identifiers below

**2. Custom Segment Lists**

Company will provide lists of users in the form of `p_user_id` to create custom audiences for customers for targeting on X.

* Line separated values
* `p_user_id`
* * (Same as provided in 1. Full Data Match section above. If the value provided in full data match is hashed then Company will provide same hashed value in audience file. If value provided is not hashed then Company will provide unhashed value.)

#### Standard Matching Requirements

If company does not use a standard ID for mapping of all customer user identifiers, this is the recommended process.

**Custom Segment Lists**

Company will provide lists of hashed common user identifiers directly to X on behalf of customers to create custom audiences.

The format of this file should be:

* Line separated values
* Hashed common user identifier (i.e. e-mail address)
* Follow file naming conventions outlined below
* Follow hashing directions for e-mail addresses below (in Hashing Directions)

#### Custom Segment List File Naming & Operations

The operation of a file will be dictated by the name of the file with the following available operations and general file naming convention: audiencename\_partnername.handle.operation.filetype

* audiencename: The name of the Custom Audience. This field is the name that will be displayed when selecting the audience in the ads.x.com campaign setup UI e.g. brand\_loyalty\_card\_holders.
* partnername: Name of the company delivering the data on behalf of advertiser e.g. company\_name.
* handle: X Account (@handle) that will have access to Custom Audiences e.g. @pepsi, @dietpepsi
* operation: new, add, remove, removeall, replace (details below)
* : Standard Unix epoch time in seconds, used to ensure that each audience file uploaded is unique
* filetype: file should be in \*.txt format

#### Creating and Updating Audiences

Create a new audience with a single file e.g. loyalty\_card\_holders\_partnername.pepsi.new\.txt

Add - Add the matches from a list to an existing audience e.g. loyalty\_card\_holders\_partnername.pepsi.add.txt

Remove - Remove the matches from a list from an existing audience Ex: loyalty\_card\_holders\_partnername.pepsi.remove.txt

Remove All - Remove the matches produced from a regularly updated cumulative list from all audiences for that client (i.e. Client’s Opt Out List). Ex: partnername.pepsi.removeall.txt

* This can be used for a comprehensive list of users who have opted-out from the Advertiser.
* X will only respect the latest list provided in this file, and will respect across all existing and future audiences for matched.

X users at the time this file was provided & processed.

Replace - Remove an existing audience and replace it with a new audience list. Ex: loyalty\_card\_holders\_partnername.pepsi.replace.txt

Overall Company Opt-Out - Company will provide a cumulative Opt-Out file to remove users that have opted out as per the Company’s Opt-Out policy.

X will only respect the latest list provided in this Company Opt-Out file and will respect across all existing and future audiences for matched X users at the time this file was provided & processed. The format of the Company Opt-Out file will be as follows: Ex: partnername.removeall.txt

Delete - Remove an existing audience from the current list of audiences e.g. Ex: loyalty\_card\_holders\_partnername.pepsi.delete.txt

#### Hashing Directions

X will securely share a base64 encoded production key via PGP for hashing common user identifiers (i.e. email addresses). Company will base64 decode the key to produce a 32-byte key to be used to perform the hashing.

Example base64 encoded key:

BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM=

Example Base64 decoded key:

/:� TшY

Normalization: Company will perform basic normalization on the common user identifiers before hashing (except on Device IDs, see Device ID Normalization section).

#### E-mail Normalization

Namely, strip out the leading and trailing spaces and also lowercase the email address.

Ex: Raw e-mail address: testemail\_Organisational\_baseball+884`@`It92I6Ev2B`.`Com

After normalization: testemail\_organisational\_baseball+884`@`it92i6ev2b`.`com

Hashed value: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec

Note: The specific number of characters for both the encoded hmac and key could vary based on the input and the encoding so the specific number of characters.

#### Device ID Normalization

We will have the same requirements for hashing of device IDs using a SHA-256 hashing algorithm and a common salt that we provide to data partners. We strip out spaces like we do with email addresses, but there is no lowercase normalization for IDFAs/Android IDs and the exact format of the IDFA/Android ID should be used.

Here is example raw format of Device IDs for iOS & Android, pre-hashing:

iOS IDFA: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431

Android ID: b5bf2122961b3595

Hashed iOS IDFA: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b

Hashed Android ID: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

#### X User ID Normalization

X IDs will still be hashed as the grouping of data - ie Customer List of @handles - is private to the advertiser even though it is not PII. We will have the same requirements for hashing of X IDs using a SHA-256 hashing algorithm and a common salt that we provide to data partners. Spaces should be stripped out of both the X ID/`@`username, but User IDs do not require normalization. @usernames should be lowercased for normalization. And the @ symbol should not be included as part of the username.

The raw ID format will be:

* User ID: 27674040
* @username: testusername

Hashed User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85

Hashed @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

### ID Sync Integration

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/reference#crm) page.

#### Pixel URL

|                                                                    |
| :----------------------------------------------------------------- |
| **Base URL**                                                       |
| [https://analytics.x.com/i/adsct](https://analytics.x.com/i/adsct) |

#### Pixel Parameters

|               |                                     |
| :------------ | :---------------------------------- |
| **Parameter** | **Description**                     |
| `p_id`        | Your X-assigned partner id          |
| `p_user_id`   | The user’s id in the partner system |

#### ID Sync Pixel:

Using an example partner id of 111, and an example `p_user_id` of abc, the constructed pixel would be the following:

```json theme={null}
    <pre class="brush: xml">
    <img height="1" width="1" src="https://analytics.x.com/i/adsct?p_id=111&p_user_id=abc" style="display:none" />
    </pre>
```

**Opt-Out File Configuration and Sending Opt-Out Files**

Partners should provide X with a list of users that to the partner’s best knowledge have selected to opt-out of targeted ad delivery. The format of file should be sent as:

|                   |                                     |                 |                                                                                                                                                                                                                                                                                                                                                                            |
| :---------------- | :---------------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Column Number** | **Column Name**                     | **Column Type** | **Description**                                                                                                                                                                                                                                                                                                                                                            |
| 1                 | Partner ID                          | string          | The “partner id” is the ID that X provides to the Partner in order to uniquely identify each Partner.                                                                                                                                                                                                                                                                      |
| 2                 | The user’s id in the partner system | string          | The `p_user_id` is the unique ID that is used to identify the user by the Partner. The file containing these opt-out users should be uploaded using the [TON upload](/x-ads-api/audiences) endpoint and the path of uploaded data should be sent to the Global Opt Out endpoint here:[PUT accounts/:account\_id/custom\_audiences/global\_opt\_out](/x-ads-api/audiences). |

**Sending Membership Updates**

As specified in our endpoint documentation, when passing users via the [POST custom\_audience\_memberships](/x-ads-api/audiences) endpoint you should pass a customer ID to enable a cookie based match. Partners sending data with a `p_id` **must** set the `user_identifier_type` to `TALIST_PARTNER_USER_ID` or `TAWEB_PARTNER_USER_ID`.

All other steps will remain the same as those listed in the [Real-Time Audience API Integration Guide](/x-ads-api/audiences)

### Custom Audiences User Data

This document outlines the format for \[Custom Audience]/x-ads-api/audiences user data.

**Data normalization**

**Device IDs**:

* IDFA - lower-cased with dashes; ex: `4b61639e-47cc-4056-a16a-c8217e029462`
* AdID - original format on device is required, not capitalized with dashes; ex: `2f5f5391-3e45-4d02-b645-4575a08f86e`
* Android id - original format on device is required, not capitalized without dashes or spaces; ex: `af3802a465767e36`

**Email Addresses**:

* lowercase, remove leading and trailing spaces; ex: `support@x.com`

**X Usernames**:

* no @, lowercased and leading and trailing spaces trimmed; ex: `jack`

**X User IDs**:

* Standard integer; ex: `143567`

**Data hashing**

The data for each line must be hashed using `SHA256`, without a salt.  Additionally, the final output hash must be in lower case. E.g., 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d and \*\*not \*\*49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D

```
# hasing user @AdsAPI using python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

#output
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d
```

Additional code samples for hashing can be found at [github.com/xdevplatform/ads-platform-tools](https://github.com/xdevplatform/ads-platform-tools).

### Custom Audiences: Web

<Frame>
  <img alt="info.png" />
</Frame>

**Information**

Partners will send a list of IDs (`p_user_ids`) to target on behalf of an advertiser. This is accomplished through an ID Sync process that builds a mapping between the `p_user_ids` and X user ID. This mapping is then used to produce lists of X User IDs that can be used for Targeting. These custom audiences will be made available on the advertiser’s specific @handle specified by the label on ads.x.com Custom Audiences Web campaign setup.

X will provide the secure pixel that can be dropped on partner tags and sites in order to match the IDs (`p_user_ids`) to X user IDs. Once the ID Sync process is complete, the targeting files will be created by the partner and will be made available to X through an HTTPS endpoint. These targeting files are ingested on a regular basis by X and are then made available in the X UI.

**X Secure Pixel**

The X secure pixel will look as follows:

[https://analytics.x.com/i/adsct?p\\\_user\\\_id=xyz\&p\_id=123](https://analytics.x.com/i/adsct?p\\_user\\_id=xyz\&p_id=123)

**`p_user_id`** - xyz represents the partner user ID that is provided by the Partner

**`p_id`** - 123 represents the unique ID for the Partner (provided by X)

**Partner HTTPS Endpoint & Targeting User File**

Partner will need to provide X with an HTTPS endpoint and credentials (username/password) that can be used to ingest the targeting file on a regular basis. A sample HTTPS endpoint will look as follows:

```
https://<partnerdomain>/twitter/partner_targeting_%Y-%M-%D.tsv.gz
```

%Y - Format Code for Year (YYYY)

%M - Format Code for Month (MM)

%D - Format Code for Day (DD)

The transmitted data will consist of the following files:

1. Partner Targeting User File
2. Targeting Conversion File

All the files will be in the TSV format, where the individual fields of each row are separated from each other by a tab character. Valid field values themselves will never contain the tab character.

**Allowed X IP Range:**

Here is the range of IPs that can be allowed for access to the Partner Endpoint.

* 199.16.156.0/22
* 199.59.148.0/22

**Partner Targeting User File:**

| **Column Number** | **Column Name**  | **Column Type** | **Description**                                                                                                                                                                                                                                                                                  |
| :---------------- | :--------------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1                 | partner id       | string          | The “partner id” is the ID that X provides to the Partner in order to uniquely identify each Partner.                                                                                                                                                                                            |
| 2                 | advertiser id    | string          | The “advertiser id” is the @handle for the advertiser.                                                                                                                                                                                                                                           |
| 3                 | p\_user\_id      | string          | The “p\_user\_id” is the unique ID that is used to identify the user by the Partner.                                                                                                                                                                                                             |
| 3                 | confidence score | integer         | The “confidence score” is optional. Our recommendation for confidence score is to use 0-100. If the use case is for retargeting, then a confidence score of “100” is a user who has been directly retargeted. Any score from 0-99 would correspond to the level of confidence of the look-alike. |
| 4                 | segment label    | string          | The “segment label” is optional. Partners can use “segment label” to specify product categories, for example. Our recommendation is to use this “segment label” as this is the human readable name for Custom Audiences in the ads.x.com UI.                                                     |

**Notes:**

Every time we receive a new Partner Targeting File, we expect this to be the full list of users that Partner recommends us to target, not incremental, unless otherwise agreed upon. We will agree with each partner what the frequency of delivery of this Partner Targeting File will be. If we do not receive a Partner Targeting File as expected, we will use the previous version with some pre-defined expiration time.

## Audience API Integration

### Overview

The Audience API was launched as part of [v4](/x-ads-api/introduction) of the Ads API and with it, brings several improvements to the legacy Audiences endpoints. This new endpoint is backed by a new Audience processing backend, and brings several improvements in terms of stability, robustness and reliability. The purpose of this guide is to highlight the differences between the Audience API and the legacy Audience upload and management processes. 

Reference documentation can be found on the [Audience API](/x-ads-api/audiences) reference documentation page. 

**Note**: All Audience user data must be SHA-256 hashed prior to upload. More details, along with the accepted user identifier types and data normalization can be found on the [user data](/x-ads-api/audiences) page.

**Changes to Audience Functionality**

The following changes to Custom Audiences have been introduced as of v4 and any deprecated endpoints will no longer be available once v3 of the Ads API has been sunset:

* **Deprecated** TON Upload:
  * GET accounts/:account\_id/custom\_audience\_changes
  * GET accounts/:account\_id/custom\_audience\_changes/:custom\_audience\_change\_id
  * POST accounts/:account\_id/custom\_audience\_changes
  * PUT accounts/:account\_id/custom\_audiences/global\_opt\_out
* **Deprecated** Real Time Audiences:
  * POST custom\_audience\_memberships
* Custom Audience:
  * The `list_type` parameter will be removed from the request and response on all [Custom Audience](/x-ads-api/audiences) endpoints. This parameter was previously used to identify the user identifier type of the Audience (i.e., email, X User ID, etc.) however Audiences now have the ability to accept multiple user identifiers for the same Audience thereby making this value irrelevant.
* General:
  * The Audience lookback window has been updated to match against users active within the past 90 days (from 30 days)
  * The minimum number of matched users required for an audience to be targetable has been decreased to 100 users (from 500 users)

<Note>
  **Prerequisites**

  * Ads API access
  * For access to the Audience endpoint, you will need to be added to an allowlist. Please fill this form and accept the new [X Ads Products and Services Agreement](/x-ads-api/introduction) if initially accepted prior to 2018-08-01
</Note>

**Audience Upload Process**

The following table lists the primary differences between the old and new Audience creation flows, with more details available further below:

| Step in Process         | Audience API                                                                                                                                                | (Deprecated) TON Upload                                                                               |
| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
| Create a shell Audience | Can be created via the \[POST custom\_audience endpoint]/x-ads-api/audiences                                                                                | Can be created via the \[POST custom\_audience endpoint]/x-ads-api/audiences                          |
| Add a new user          | Use the `operation_type` `Update` with the [Audience endpoint](/x-ads-api/audiences)                                                                        | Use the `operation` `ADD` with the [POST custom\_audience\_changes](/x-ads-api/audiences) endpoint    |
| Remove a user           | Use the `operation_type` `Delete` with the [Audience endpoint](/x-ads-api/audiences)                                                                        | Use the `operation` `REMOVE` with the [POST custom\_audience\_changes](/x-ads-api/audiences) endpoint |
| Opting-Out Users        | Use the `operation_type` `Delete` with the [Audience endpoint](/x-ads-api/audiences) and the corresponding `custom_audience_id`s that the user is a part of | Use the [Global opt-out endpoint](/x-ads-api/audiences)                                               |

**Note** Any audiences being updated or opted-out via the TON Upload path must have a corresponding list uploaded via the [TON Upload](/x-ads-api/audiences) endpoint and associated with an Audience using the [custom\_audience\_changes](/x-ads-api/audiences) endpoint.

**Rate Limiting**

The Audience API endpoint has a rate limit of 1500/1min per account. There are no limits on the number of users that can be sent in a single payload. The only constraints on the payload are:

1\. Total number of operations: 2500 operations

2\. Maximum payload size: 5,000,000 bytes

**Audience User Management**

In order to create a new Audience, the following steps are required

### Create a new Custom Audience

Create a new Custom Audience "shell" using the \[POST custom\_audience]/x-ads-api/audiences endpoint and retrieve the corresponding Custom Audience `id`. This step is required if creating an Audience from scratch. If updating an existing Audience, skip to the next section

### Add Users to an Audience

Use the [POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/users](/x-ads-api/audiences) with the Custom Audience `id` and a sample payload like so:

POST [https://ads-api.x.com/11/accounts/18ce54d4x5t/custom\_audiences/1nmth/users](https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users)

```
    # All values must be hashed, unhashed values are used in this example for illustrative purposes
    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "handle": [
                "x",
                "adsapi"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]
```

In order to add a user to an Audience, use the `operation_type` `Update`. The new Audience interface enables the ability to pass in multiple user keys for a single user. Each object in the array of JSON objects corresponds to a single user. Using the example payload above, the request will add two users to an Audience, one with an `email` and `handle` and another with an `email` and `twitter_id`. 

#### Remove Users from an Audience

Similar to the process outlined for adding users, users can be removed from an audience using like so:

POST [https://ads-api.x.com/11/accounts/18ce54d4x5t/custom\_audiences/1nmth/users](https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users)

```
    # All values must be hashed, unhashed values are used in this example for illustrative purposes
    [
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "twitter_id": [
                "783214",
                "1225933934"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]
```

The `operation_type` must be set to `Delete` and users will be matched on any keys that were present when adding users to the audience. For example, if a user was added to an audience using an `email` and `twitter_id`, then the same user can be removed using any one of these keys, i.e., either `email` or `twitter_id` or both.

Additionally, it is possible to add and remove users from an Audience within the same request. The endpoint supports multiple `operation_type` per request.

#### Opt-Out Users

With the deprecation of the global opt-out endpoint, partners are required to `Delete` any users that have opted-out of any Audiences. There are a few ways to achieve this:

1. Keep track of which users are part of which Audiences and remove these users individually from each Audience.
2. Remove the user from **all** Audiences associated with an Ads account.

**General Best Practices**

* We strongly recommend calling this endpoint in near real-time batches to avoid spiky queues which take longer to process and in general cause unnecessary load on our system. This also ensures users are available for campaign targeting sooner.
* A successful API call will return a `success_count` and `total_count` corresponding to the number of `user` objects that have been received in the request.
* 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

***

## Full API Reference

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.


# Audiences API Reference
Source: https://docs.x.com/x-ads-api/audiences/reference

Endpoint reference for the X Ads Audiences API, including keyword insights, custom audience management, and user list upload request and response details.

## API Reference

### Keyword Insights

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="enum">
  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`.<br /><br />
  Possible values: `DAY`, `HOUR`
</ParamField>

<ParamField type="string">
  A comma-separated string of keywords to narrow search by. All keywords are OR'ed with one another.<br /><br />
  **Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.
</ParamField>

<ParamField type="string">
  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).
</ParamField>

<ParamField type="string">
  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).<br /><br />
  **Note**: Defaults to the current time.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  A comma-separated string of keywords to exclude. All negative keywords are OR'ed with one another.<br /><br />
  **Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
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")**\*

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/369a02c0adc626ff6a06#?env%5BTwitter%20Ads%20API%5D=W3sia2V5IjoiYWNjb3VudF9pZCIsInZhbHVlIjoieW91cl9hZHNfYWNjb3VudF9pZCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidmVyc2lvbiIsInZhbHVlIjoiNSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfa2V5IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX2tleSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfc2VjcmV0IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX3NlY3JldCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYWNjZXNzX3Rva2VuIiwidmFsdWUiOiJ5b3VyX2FjY2Vzc190b2tlbiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidG9rZW5fc2VjcmV0IiwidmFsdWUiOiJ5b3VyX3Rva2VuX3NlY3JldCIsImVuYWJsZWQiOnRydWV9XQ==">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the tailored audience you are operating with in the request.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**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")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The account you wish to grant the tailored audience permissions for.
</ParamField>

<ParamField type="enum">
  The type of access to the tailored audience that the `granted_account_id` should have.<br /><br />
  Possible values: `READ_ONLY`, `READ_WRITE`
</ParamField>

<ParamField type="string">
  A reference to the tailored audience you are operating with in the request.
</ParamField>

**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")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the tailored audience you are operating with in the request.
</ParamField>

<ParamField type="string">
  A reference to the tailored audience permission you are operating with in the request.
</ParamField>

**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")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the custom audience you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  When `false`, includes line items that have `servable=false` status.
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

**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")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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")

<ParamField type="enum">
  The per `users` group operation type being performed.<br /><br />
  Possible values: `Update`, `Delete`
</ParamField>

<ParamField type="object">
  A JSON object containing the `users` array, the `effective_at` and `expires_at` timestamps.
</ParamField>

<ParamField type="array">
  An array of JSON objects containing all params for an individual user.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

Given the multi-key approach to the `users` object, each element of this object is documented below:

<ParamField type="array">
  Email address(es) for the user.
</ParamField>

<ParamField type="array">
  IDFA/AdID/Android ID.
</ParamField>

<ParamField type="array">
  The @handle(s) belonging to the user.
</ParamField>

<ParamField type="array">
  The X ID belonging to the user.
</ParamField>

<ParamField type="array">
  Phone number(s) for the user.
</ParamField>

<ParamField type="array">
  The user's ID in the partners' system.
</ParamField>

#### Example Request[](#example-request "Permalink to this headline")

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users`

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    [
      {
        "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")

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "success_count": 4,
        "total_count": 4
      }
    }
```

### Custom Audience Permissions

<Button href="https://app.getpostman.com/run-collection/369a02c0adc626ff6a06#?env%5BTwitter%20Ads%20API%5D=W3sia2V5IjoiYWNjb3VudF9pZCIsInZhbHVlIjoieW91cl9hZHNfYWNjb3VudF9pZCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidmVyc2lvbiIsInZhbHVlIjoiNSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfa2V5IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX2tleSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfc2VjcmV0IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX3NlY3JldCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYWNjZXNzX3Rva2VuIiwidmFsdWUiOiJ5b3VyX2FjY2Vzc190b2tlbiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidG9rZW5fc2VjcmV0IiwidmFsdWUiOiJ5b3VyX3Rva2VuX3NlY3JldCIsImVuYWJsZWQiOnRydWV9XQ==">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the custom audience you are operating with in the request.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**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")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The account you wish to grant the custom audience permissions for.
</ParamField>

<ParamField type="enum">
  The type of access to the custom audience that the `granted_account_id` should have.<br /><br />
  Possible values: `READ_ONLY`, `READ_WRITE`
</ParamField>

<ParamField type="string">
  A reference to the custom audience you are operating with in the request.
</ParamField>

**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")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the custom audience you are operating with in the request.
</ParamField>

<ParamField type="string">
  A reference to the custom audience permission you are operating with in the request.
</ParamField>

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the custom audience you are operating with in the request.
</ParamField>

<ParamField type="string">
  A reference to the custom audience permission you are operating with in the request.
</ParamField>

**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")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="enum">
  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.<br /><br />
  Possible values: `OWNER`, `SHARED`
</ParamField>

<ParamField type="string">
  An optional query to scope resource by `name`.<br /><br />
  **Note**: This performs case-insensitive prefix matching.<br /><br />
  Min, Max length: `1`, `255`
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired custom audiences by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**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")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the custom audience you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**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")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The display name for this audience. Unique name value must be used. Failure to do so will result in an error.
</ParamField>

<ParamField type="string">
  A description for this audience.
</ParamField>

**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")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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 specific 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the Custom Audience you are operating with in the request.
</ParamField>

<ParamField type="string">
  The display name for this audience. Unique name value must be used. Failure to do so will result in an error.
</ParamField>

<ParamField type="string">
  A description for this audience.
</ParamField>

**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")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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**

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

* 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="enum">
  The type of audience to create.<br /><br />
  Possible values: `FLEXIBLE`, `MOBILE_AUDIENCE`
</ParamField>

<ParamField type="array">
  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`.
</ParamField>

<ParamField type="string">
  The display name for the audience. Unique name value must be used. Failure to do so will result in an error.
</ParamField>

<ParamField type="enum">
  The per item operation type being performed.<br /><br />
  Possible values: `Create`, `Update`, `Delete`
</ParamField>

<ParamField type="enum">
  The logical relationship between the child segments in its parent (containing) object. Required if child\_segments is non-empty for the parent object.<br /><br />
  Possible values: `AND`, `OR`
</ParamField>

<ParamField type="int">
  An integer value specifying the range of days within which the user has taken the specific action and qualified for the given custom audience.<br /><br />
  Possible values: `1`, `7`, `14`, `30`
</ParamField>

<ParamField type="object">
  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.
</ParamField>

<ParamField type="string">
  The id of the custom audience to use as a child segment.
</ParamField>

<ParamField type="int">
  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.
</ParamField>

<ParamField type="string">
  The comparator to the `frequency` passed in the request.<br /><br />
  **Note**: In the values below, `GTE` refers to greater than or equal, `LT` to less than, and so on.<br /><br />
  Possible values: `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT`
</ParamField>

<ParamField type="boolean">
  Negates the segment and thus is excluded in the combination.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences`

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    [
      {
        "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")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the custom audience you are operating with in the request.
</ParamField>

**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")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**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")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A description for this audience.
</ParamField>

**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")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="enum">
  The per item operation type being performed.<br /><br />
  Possible values: `Update`, `Delete`
</ParamField>

<ParamField type="object">
  A JSON object containing the `emails` array and the `expires_at` timestamp.
</ParamField>

<ParamField type="array">
  An array of hashed email addresses.
</ParamField>

<ParamField type="string">
  The UTC time at which the Do Not Reach List association(s) should expire. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
</ParamField>

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the Do Not Reach List you are operating with in the request.
</ParamField>

<ParamField type="enum">
  The per `users` group operation type being performed.<br /><br />
  Possible values: `Update`, `Delete`
</ParamField>

<ParamField type="object">
  A JSON object containing the `emails` array and `expires_at` timestamp.
</ParamField>

<ParamField type="array">
  An array of JSON objects containing all params for an individual user.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

Given the multi-key approach to the `users` object, each element of this object is documented below:

<ParamField type="array">
  Email address(es) for the user.
</ParamField>

<ParamField type="array">
  Phone number(s) for the user.
</ParamField>

**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")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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
      }
    }
```


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

Create, manage, and optimize advertising campaigns on X. Define budgets, targeting, creatives, and bidding strategies using the Ads API.

<BlueprintMark name="targeting" />

**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.

<Note>
  <strong>Looking for detailed endpoint documentation?</strong><br />
  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
  <a href="/x-ads-api/campaign-management/reference">Campaign Management API Reference</a> page.
  Old deep links (e.g. <code>#get-accounts-account-id-campaigns</code>) will automatically redirect there.
</Note>

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

Programmatically schedule campaigns and manage ads on X through this suite of APIs.

## What you can promote

### [Promoted Ads](https://business.x.com/help/what-are-promoted-tweets)

* 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/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)

* Promoted Accounts are part of Who to Follow, which suggests accounts that people don’t currently follow and may find interesting. Promoted Accounts help introduce an even wider variety of accounts people may enjoy.
* Promoted Accounts for Timeline, associate a Promoted Tweet with a Promoted Account campaign and will display in user timelines.

Promoted Trends are not available in the Ads API.

## Campaigns and Ad Groups (Line Items)

Campaigns define the schedule and budget of an ad. The advertiser specifies a daily and overall budget. The campaign can be bound to a specific start and end time or run continuously until the budget is spent. The budget comes from one of the Funding Instruments of the advertising account. Campaign identifiers (:campaign\_id) are the base-36 representation of the base-10 value we present in the X Ads UI.

Advertising accounts are limited to a maximum of 200 active campaigns. This limit can be raised to 4,000 active campaigns manually by the advertiser’s X Account Manager upon request. A campaign is considered active until it reaches its end time or gets deleted. Paused campaigns are considered active until their designated end times.

Line items spend the budget defined by a campaign. Line items pull together the per-engagement bid, the Tweet or account to promote, and the targeting rules.

## Analytics

The X Ads API offers a set of analytics endpoints to track and optimize ad performance. Please see Analytics and Analytics Best Practices for more information.

For the billing metric, the data may not be finalized until three days after the event. Before that point, the data should be considered speculative. The final billable number will always be less than the speculative amount. The billable number is corrected for spam and related low-quality traffic. See Timezones for other considerations regarding time.

## Creating a Campaign - Step-by-Step

The following example assumes you have installed, configured, and authorized your app and user using [twurl](https://github.com/twitter/twurl). twurl is a command-line tool in the spirit of cURL that gracefully handles X OAuth authentication. twurl is a great tool for quickly testing and debugging Ads API (and REST API) functionality. To see the full headers of the request and response, use `-t` to trace the call, roughly equivalent to cURL’s `-v` option.

**For this example, we will create a Promoted Ads campaign that will be targeted by keyword.**

1. **Retrieve the account id.**

```
twurl -H ads-api.x.com /9/accounts/
```

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
    }
  },
  "data": [
    {
      "name": "Test account for @AdsAPI",
      "timezone": "America/Los_Angeles",
      "timezone_switch_at": null,
      "id": "xxxxxx",
      "created_at": "2014-03-09T00:41:49Z",
      "salt": "f9f9d5a5f23075c618da5eb1d1a9df57",
      "updated_at": "2015-01-29T00:41:49Z",
      "approval_status": "ACCEPTED",
      "deleted": false
    }
  ],
  "data_type": "account",
  "total_count": 1,
  "next_cursor": null
}
```

2. **Retrieve the funding instrument id.**

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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "cancelled": true,
      "created_at": "2014-03-09T00:41:49Z",
      "credit_limit_local_micro": null,
      "currency": "USD",
      "deleted": false,
      "description": null,
      "end_time": null,
      "funded_amount_local_micro": null,
      "id": "yyyy",
      "type": null,
      "updated_at": "2014-05-29T00:41:49Z"
    }
  ],
  "data_type": "funding_instrument",
  "next_cursor": null,
  "request": {
    "params": {
      "account_id": "xxxxxx"
    }
  },
  "total_count": 1
}
```

3. **Create a campaign and associate it with the funding instrument.**

Specify a start time and a budget for the campaign. For the purpose of this example, we will use a budget of \$500 and for the daily limit, \$50.

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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "created_at": "2015-02-09T00:00:00Z",
    "currency": "USD",
    "daily_budget_amount_local_micro": 50000000,
    "deleted": false,
    "end_time": null,
    "funding_instrument_id": "yyyy",
    "id": "92ph",
    "name": "My First Campaign",
    "entity_status": "PAUSED",
    "standard_delivery": true,
    "total_budget_amount_local_micro": 500000000,
    "updated_at": "2015-02-09T00:00:00Z"
  },
  "data_type": "campaign",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "daily_budget_amount_local_micro": 50000000,
      "funding_instrument_id": "yyyy",
      "name": "My First Campaign",
      "total_budget_amount_local_micro": 500000000
    }
  }
}
```

4. **Create a line item associated with the campaign.**

Now that we have a campaign id, we can create a line item to associate with it. The line item wraps the bid price, targeting, and actual creative portion of the campaign. For this line item, we will be promoting tweets with a bid of \$1.50.

```
twurl -H ads-api.x.com -d "campaign_id=XXXX&bid_amount_local_micro=1500000&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&objective=ENGAGEMENTS&entity_status=PAUSED" /9/accounts/xxxxxxx/line_items
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data_type": "line_item",
  "data": {
    "bid_type": "MAX",
    "name": "Untitled",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "bid_amount_local_micro": 1500000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "azjx",
    "entity_status": "PAUSED",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2015-02-09T00:00:00Z",
    "updated_at": "2015-02-09T00:00:00Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "92ph",
    "deleted": false
  },
  "request": {
    "params": {
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 1500000,
      "product_type": "PROMOTED_TWEETS",
      "entity_status": "PAUSED",
      "account_id": "xxxxxxx",
      "campaign_id": "92ph"
    }
  }
}
```

5. **Create a targeting profile associated with the line item.**

With the line item created, we can assign targeting criteria. We want to target the phrase keywords “grumpy cat” in the San Francisco Bay Area location. This is going to require a location id lookup and two targeting\_criteria POST requests.

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

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "name": "San Francisco-Oakland-San Jose CA, US",
      "targeting_type": "LOCATION",
      "targeting_value": "5122804691e5fecc"
    }
  ],
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "location_type": "CITY",
      "q": "San Francisco"
    }
  }
}
```

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

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "created_at": "2015-02-09T00:00:15Z",
    "deleted": false,
    "id": "2u3be",
    "line_item_id": "yyyy",
    "name": "San Francisco-Oakland-San Jose CA, US",
    "targeting_type": "LOCATION",
    "targeting_value": "5122804691e5fecc",
    "updated_at": "2013-05-30T21:01:35Z"
  },
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "line_item_id": "yyyy",
      "targeting_type": "LOCATION",
      "targeting_value": "5122804691e5fecc"
    }
  }
}
```

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

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "created_at": "2015-02-09T00:00:20Z",
    "deleted": false,
    "id": "2u3bd",
    "line_item_id": "yyyy",
    "name": "grumpy cat",
    "targeting_type": "PHRASE_KEYWORD",
    "targeting_value": "grumpy cat",
    "updated_at": "2013-05-30T18:05:35Z"
  },
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "line_item_id": "yyyy",
      "targeting_type": "PHRASE_KEYWORD",
      "targeting_value": "grumpy cat"
    }
  }
}
```

6. **Finally, un-pause the line item.**

```
twurl -H ads-api.x.com -X PUT "/9/accounts/xxxxxx/line_items/yyyy/?entity_status=ACTIVE"
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data_type": "line_item",
  "data": {
    "bid_type": "MAX",
    "name": "grumpy cat",
    "placements": [],
    "bid_amount_local_micro": 1500000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "yyyy",
    "entity_status": "ACTIVE",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2015-02-09T00:00:20Z",
    "updated_at": "2015-02-09T00:00:20Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "dy1f",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "yyyy",
      "entity_status": "ACTIVE",
      "account_id": "xxxxxx"
    }
  }
}
```

That’s it! We now have an active, targeted, and funded Promoted Tweets in Timelines campaign which is running.

### Objective Based Campaigns

Objective-based campaigns and pricing allow advertisers to pay for the actions that are aligned with their marketing objectives. To support these, set the appropriate `objective` on line items.

The parameter used on the line item write endpoints and returned on the read endpoints, is `objective`. This field has the following possible values as of today:

* `APP_ENGAGEMENTS`
* `APP_INSTALLS`
* `FOLLOWERS`
* `ENGAGEMENTS`
* `REACH`
* `VIDEO_VIEWS`
* `PREROLL_VIEWS`
* `WEBSITE_CLICKS`

Objectives impact how we optimize campaigns in our auctions and how we bill on those campaigns. We enable pricing based on objective, such as CPAC for `APP_ENGAGEMENTS`, CPAC *or* CPI for `APP_INSTALLS`, CPLC for `WEBSITE_CLICKS`, CPF for `FOLLOWERS`, CPE for `ENGAGEMENTS`, and CPM for `REACH`.

Mobile app promotion campaigns are required to contain either the `APP_ENGAGEMENTS` or `APP_INSTALLS` objective.

**Note:** Line items with different objectives are not allowed under the same campaign.

| Campaign objective | API objective     | Media in Tweets                                                                                                                                                                                                                                        | Pricing model                       |
| :----------------- | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- |
| App re-engagements | `APP_ENGAGEMENTS` | Image or video app download card required.                                                                                                                                                                                                             | CPAC                                |
| App installs       | `APP_INSTALLS`    | Image or video app download card required.                                                                                                                                                                                                             | CPAC or CPI (set using `charge_by`) |
| Reach              | `REACH`           | No restrictions.                                                                                                                                                                                                                                       | CPM                                 |
| Followers          | `FOLLOWERS`       | Tweet not required, but recommended. There are no media restrictions on Tweets for Followers campaigns, though we recommend text-only Tweets. [More information](https://business.x.com/en/help/campaign-setup/create-a-followers-campaign.html#serve) | CPF                                 |
| Engagements        | `ENGAGEMENTS`     | No restrictions.                                                                                                                                                                                                                                       | CPE                                 |
| Video Views        | `VIDEO_VIEWS`     | Video conversation card, video, or GIF required.                                                                                                                                                                                                       | CPV or cost per 3s/100% view        |
| Pre-roll views     | `PREROLL_VIEWS`   | Video required.                                                                                                                                                                                                                                        | CPV or cost per 3s/100% view        |
| Website Clicks     | `WEBSITE_CLICKS`  | Website card recommended, but not required. Tweet must have either a website card or a website link (not both).                                                                                                                                        | CPLC                                |

### Funding Instruments

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

Descriptive: `account_id`, funding instrument `id`, funding instrument `type`, `description`, and `io_header`(insertion order header ID). Note that a single `io_header` may be associated with multiple funding instruments.

Funding ability: `able_to_fund` and `reasons_not_able_to_fund`.

Time: `created_at`, `updated_at`, `start_time`, and `end_time` represented by a string, formatted as “%Y-%m-%dT%l:%M:%S%z”.

Boolean status: `paused`, `deleted`, and `cancelled` (true or false).

Financial: `currency` ([ISO-4217](http://en.wikipedia.org/wiki/ISO_4217) format), `credit_limit_local_micro`, `credit_remaining_local_micro`, and `funded_amount_local_micro`. 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.

#### Attribute Details

`credit_limit_local_micro` is only valid for `CREDIT_CARD` or `CREDIT_LINE` type funding instruments and represents the credit limit for that instrument.

`funded_amount_local_micro` is only valid for `INSERTION_ORDER` type funding instruments and represents the allocated budget.

`credit_remaining_local_micro` is valid for `CREDIT_LINE` and `AGENCY_CREDIT_LINE` type funding instruments. It represents the `credit_limit_local_micro` minus the amount already spent on that funding instrument. It does not represent the difference between `funded_amount_local_micro` and the amount spent. We draw a distinction between credit limit and funded amount because they represent different underlying funding methods and spending agreements we have with advertisers.

#### Types of Funding Instruments

**Credit Cards**

Typically used by self-serve advertisers (without an account manager).

**Credit Lines**

These are in the form of insertion orders (IOs) and are set by account managers.

**Multi-Handle Credit Lines**

Advertisers can fund campaigns across multiple handles with this type of credit line. This feature is enabled by their X Account Manager, associating the different @handles to a specific credit line.

For example, @NikeSB and @NikeFuel can both have access to the @Nike credit line. This funding instrument is available just like any other. You retrieve the data by submitting a GET request to the funding\_instrument endpoint. Here is a sample response (note the `CREDIT_LINE` type).

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
GET https://ads-api.x.com/5/accounts/a0b1c3/funding_instruments

{
    "request": {
        "params": {
            "account_id": "a0b1c3"
        }
    },
    "data": [
        {
            "start_time": "2013-05-30T04:00:00Z",
            "description": "FakeNike - Credit Line",
            "credit_limit_local_micro": 150000000000,
            "end_time": null,
            "cancelled": false,
            "id": "i1234",
            "paused": false,
            "account_id": "a0b1c3",
            "reasons_not_able_to_fund": [],
            "io_header": null,
            "currency": "USD",
            "funded_amount_local_micro": 0,
            "created_at": "2013-05-30T18:16:38Z",
            "type": "CREDIT_LINE",
            "able_to_fund": true,
            "updated_at": "2013-05-30T18:16:38Z",
            "credit_remaining_local_micro": 123661919751,
            "deleted": false,
        }
    ],
    "data_type": "funding_instrument",
    "total_count": 1,
    "next_cursor": null
}
```

The only thing particular about this funding instrument is the type and the fact that it is available to all the accounts that were associated to it. Of course, the remaining credit is impacted by all campaigns funded by this instrument, across all accounts sharing it. The details of what accounts are associated to a specific credit line are not available via the API (nor via ads.x.com).

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/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/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/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
* **X Profiles & Tweet Details**: 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

#### Understanding targeting types

**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/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/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/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/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/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.

[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/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/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.
* Users cannot target platforms that are broader than devices. I cannot target iOS and iPad Air.

\[Tailored Audiences]/x-ads-api/audiences: Reach users through an approved ads partner to target groups of customers and connect with them on 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/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**

Tweet engager retargeting enables advertisers to target audiences across devices who have previously been exposed to or engaged with their promoted or organic Tweets on X. With this targeting advertisers can follow up with people who saw or engaged with an advertiser’s content on X and are most likely to further engage or convert with subsequent messaging or offers. Users will be eligible for targeting within minutes of exposure or engagement and will remain eligible for up to 90 days afterwards for engagements and 30 days for exposures.

Tweet Engager Targeting Types:

* `ENGAGEMENT_TYPE` which accepts either `IMPRESSION` or `ENGAGEMENT` as a targeting value. This specifies whether you wish to target exposed users (`IMPRESSION`) or engaged users (`ENGAGEMENT`).
* `CAMPAIGN_ENGAGEMENT` uses a campaign ID as the targeting value. Users who engaged with or were exposed to this campaign (depending on `ENGAGEMENT_TYPE`) are the ones who will be targeted.
* `USER_ENGAGEMENT` which uses the promoted user ID as the targeting value to target users who were exposed to or engaged with an advertiser’s organic content (depending on `ENGAGEMENT_TYPE`). This must be the promoted user ID associated with the Ads account.

*Note:* `ENGAGEMENT_TYPE` is required in addition to at least one valid `CAMPAIGN_ENGAGEMENT` or `USER_ENGAGEMENT` value. Both tweet engager targeting types may be present and multiple campaigns may be targeted on a given line item.

**Video Viewer Targeting**: Video viewer targeting builds on Tweet engager targeting to enable advertisers to target audiences who have previously watched part or all of a video on X. Advertisers can target organic videos, promoted videos, or both. Promoted videos are not limited to video view objective campaigns or line items.

Video Viewer Targeting Types:

* `VIDEO_VIEW` for users who have clicked to play the video or have viewed 3 seconds of autoplay
* `VIDEO_VIEW_PARTIAL` for users who have viewed 50% of the video
* `VIDEO_VIEW_COMPLETE` for users who have viewed at least 95% of the video

As with Tweet engager targeting, one or both of the following must also be present in targeting criteria for the line item when `ENGAGEMENT_TYPE` is used:

* `CAMPAIGN_ENGAGEMENT` uses a campaign ID as the targeting value. Users who watched a video (based on `ENGAGEMENT_TYPE`) in this campaign are the ones who will be targeted.
* `USER_ENGAGEMENT` which uses the promoted user ID as the targeting value to target users who watched a video (based on `ENGAGEMENT_TYPE`) in an advertiser’s organic content. This must be the promoted user ID associated with the Ads account.

**Keyword Types**

See our support document on [keyword targeting](https://business.x.com/en/help/campaign-setup/campaign-targeting/keyword-targeting.html) for a conceptual overview.

* **Broad** (default value): match all words, independent of order. Not sensitive to capitalization, plurals or tense. Will automatically be expanded when possible (i.e. “car repair” would also match “automobile fix”). If you want to target without expansion, you need to add a + sign before the keywords, like “+boat +jet”. Using keywords without the + will default to Broad Match.
* **Unordered** (deprecated): match all words, independent of order. Not sensitive to capitalization, plurals or tense.
* **Phrase**: match the exact keywords string, other keywords can be present.
* **Exact**: match exactly the keywords string, not any others.
* **Negative**: avoid matching searches that include all of these keywords somewhere in the query, regardless of the order in which they are written, even if other words are present.
* **Negative Phrase**: avoid matching searches that include this exact keywords string somewhere in the query, even if other words are present.
* **Negative Exact**: avoid matching searches that exactly match these keywords and contain no other words.
   

**Emoji targeting**

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/reference#get-accounts-account-id-targeting-criteria).

#### Targeting Criteria Combinations

**Updated Campaign Workflow**

Create campaigns which target broadly with geo, gender, language, and device/platform criteria. Advertisers can then combine the broad targeting with additional targeting criteria (e.g. interests, keywords, followers, tailored audiences, TV). **If no targeting criteria is specified for a line item, the line item will target all users worldwide.**

|                    |                       |
| :----------------- | :-------------------- |
| “Primary” Types    | Other Types           |
| Followers          | Locations             |
| Tailored Audiences | Gender                |
| Interests          | Languages             |
| Keywords           | Devices and platforms |
| TV                 | Age                   |

Targeting criteria will be combined for your ad group such that:

* “Primary” Targeting Types will get **∪**‘d (i.e. put in a logical union).
* Other Targeting Types will get **AND**‘d.
* Same types will get **OR**‘d.

**Some examples**

At a glance: \[(**Followers**) ∪ (**Tailored Audiences**) ∪ (**Interests**) ∪ (**Keywords**)] AND (**Location**) AND (**Gender**) AND (**Languages**) AND (**Devices and Platforms**)

A Geo example:

Let’s say we want an ad group for our campaign to serve targeting:

* X users in the U.S., England, and Canada (Location)
* who are Women (Gender)
* derived from Tailored Audiences list (“Primary”)
* with Keywords (“Primary”)

The targeting criteria will be:

\[**US** OR **GB** OR **CA**] AND \[**Female**] AND \[**Tailored Audiences** ∪ **Keyword**]

### Additional examples

* Select Gender and Geo but no primary: (**Male**) AND (**US** OR **GB**)
* Select Gender, Geo, Interest: (**Female**) AND (**CA**) AND (**Computers** OR **Technology** OR **Startups**)
* Select Gender, Geo, Interest, Tailored Audiences, Keywords: (**Male**) AND (**GB**) AND (**Cars** ∪ **Tailored Audiences for CRM** ∪ **autocross**)

### Budget Pacing

Advertisers now have more control over how fast their daily budgets are spent on your Promoted Tweet and Account campaigns. Enabling standard delivery, which is the default, ensures an even spend rate throughout the day.

By turning **off** standard delivery, we will serve impressions and generate engagements as quickly as possible until your daily budget is exhausted, which may be quite early on in the day depending on targeting and competition. This is called accelerated delivery.

**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/reference#get-accounts-account-id-campaigns)).

**Notes**

* “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).

### Target Bidding

Campaign management

#### Bid Strategy

We have introduced the concept of Bid Strategy to simplify campaign creation workflow and reduce confusion about combinations of multiple parameters.

All previous (marked as legacy) combinations of parameters can be achieved by setting an equivalent goal parameter. Further information can be found in the announcement [here](https://devcommunity.x.com/t/ads-api-version-10/158787/1#changed-default-bid_strategy-values-9).

As example:

|                        |                                                                                                 |                                                            |
| :--------------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------- |
| **Campaign Objective** | **Legacy**                                                                                      | **Ads API v10+**                                           |
| App Installs           | `bid_type`= `AUTO`<br /><br />`bid_unit` = `APP_INSTALLS`<br /><br />`charge_by` = `APP_CLICKS` | `goal` = `APP_INSTALLS`<br /><br />`bid_strategy` = `AUTO` |
| Website Clicks         | `bid_type` = `TARGET` (Note: `bid_unit` was not needed for some campaign objectives)            | `bid_strategy` = `TARGET`                                  |

#### Target Bidding

Using target bidding, you can specify a target cost you want to pay and the X Ads platform will optimize your campaign for performance while staying near or below your target cost.

This feature gives you the flexibility to reach users who are especially likely to take the desired action (such as a link click, a lead or a follow) while maintaining cost control. This is a powerful feature for advertisers who desire more options for campaign setup and optimization (including bidding options).

For line items with compatible campaign objectives, we’ve introduced a new pricing mechanism for bid amount that lets you specify a target cost you want to pay. Our ad platform dynamically bids on your behalf to help you drive more results, while working to keep your average cost within 20% of your specified target. The `bid_strategy` setting on line items may be set with a value of `TARGET` to enable target bidding on relevant campaign objectives, such as:

* `WEBSITE_CLICKS`
* `WEBSITE_CONVERSIONS` 
* `APP_INSTALLS` 
* `APP_ENGAGEMENTS`
* `REACH`

### Country Targeting and Display Requirements

Campaign management

Country-specific targeting and display requirements are contained on this page. These requirements must be adhered to by all partners.

#### Russia

[X’s Ads Policies](https://support.x.com/groups/58-advertising/topics/249-advertiser-policies/articles/20171727-illegal-products-and-services) prohibit advertisers from targeting Russia with advertisements that are not in the Russian language. When your users specifically target Russia, you must display the following warning message to your users:

Ads targeting Russia must be in the Russian language.

### Partner Managed Funding Instruments

The onboarding flow configures an [ads.x.com](https://ads.x.com) account for the X account, which can be managed by the partner through the Ads API, and whose advertising spend is billed to the partner.
 

#### Partner Initial Set-up

The process to initially set-up a new PMFI Ads API partner takes up to 3-weeks from exchange of required information. The following must be shared with your technical contacts at X, as well as the X contact managing the integration with the partner in order to get the process started:

* **The partner must share their PGP/GPG public key.** A shared secret key needs to be exchanged between the Ads API partner and X. This will be used to verify data during the onboarding flow.
* **The** `app_id` **or** `consumer_secret` **for the [X app](/resources/fundamentals/developer-apps) that will be used for Ads API access.** You can view and edit your existing X apps via the [app dashboard](https://developer.x.com/content/developer-twitter/en/apps) if you are logged into your X account on developer.x.com. If you need to create a X app, you will need to have an approved [developer account](/resources/fundamentals/developer-portal). X allows one app for production+sandbox and one optional app for sandbox-only access. The X app must be created on a corporate, partner-controlled X handle.
   

#### Advertiser Onboarding Flow

The advertiser onboarding flow occurs via a web browser in the following way:

1. The user starts the onboarding flow on the partner’s website and enters the handle they want to onboard.
2. The partner redirects the user to a URL on [ads.x.com](https://ads.x.com) with a signed payload. This payload contains the partner’s API `app_id`, the X `user_id` of the X handle which is to be onboarded and a callback URL and other fields documented below.
3. The user is asked to sign into [ads.x.com](http://ads.x.com) using the standard x.com login page.
4. Once the user is logged in, the onboarding process is initiated. This step includes ad review, account validation and other checks.
5. When all onboarding tasks are completed, the user is redirected to the callback URL that was provided by the Ads API partner, with a payload that indicates success or failure. This includes the 3-legged authorization process.
    

#### Onboarding redirect payload

URL for redirect:

[https://ads.x.com/link\\\_managed\\\_account](https://ads.x.com/link\\_managed\\_account)

The redirect URL will be called with the following parameters:

|                      |                                                             |                                                                                                                                                                                                                                                                                                                                                    |
| :------------------- | :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                 | Type                                                        | Description                                                                                                                                                                                                                                                                                                                                        |
| callback\_url        | URL encoded string                                          | user will be redirected to this url after the account link process completes, regardless of outcome. See the partner redirect url section for protocol details                                                                                                                                                                                     |
| client\_app\_id      | integer                                                     | X API client app id, used to identify the managing partner                                                                                                                                                                                                                                                                                         |
| promotable\_user\_id | integer                                                     | X user\_id of the @handle whose promotions are to be managed by the managing partner. Used to make sure it is the same as the user who logs into ads.x.com to complete the linking process                                                                                                                                                         |
| fi\_description      | URL encoded String (max 255 characters)                     | funding instrument name. This will be displayed in the description field in the API when the funding instrument is retrieved. If a funding\_instrument description is given, the existing funding\_instrument will be paused, and a new managed partner funding instrument will be set up. (if one exists with the same name, nothing will happen) |
| timezone             | String, in Area/Location format                             | This will be the timezone used to determine the day to which daily budgets apply, and in which charges will be aggregated                                                                                                                                                                                                                          |
| currency             | ISO 4217 Currency Code                                      | Currency that will be used to enter bids, and in which charges will be billed                                                                                                                                                                                                                                                                      |
| country              | ISO 3166-1 alpha 2 Country Code                             | Billing Country for the account                                                                                                                                                                                                                                                                                                                    |
| signature            | URL encoded, base64 encoded binary code, as explained below | signature that combines a shared secret and the other parameters to verify authenticity of the call, as well as validity of the parameters.                                                                                                                                                                                                        |

#### Callback URL payload

The base redirect URL is provided using the callback\_url parameter on the account link request (see above). The parameters added by [ads.x.com](https://ads.x.com) are:

|                         |                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| :---------------------- | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                    | Type                                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| status                  | string                                                      | **OK** an account was created, or an existing, eligible account was found.<br /><br />**ACCOUNT\_INELIGIBLE** if partner specific constraints are not met **USER\_MISMATCH** the X account used to sign into ads.x.com was different from the promotable\_user\_id on the account link request **INCOMPLETE\_SERVING\_BILLING\_INFO** timezone, currency or country were not specified **INVALID\_COUNTRY** an invalid country value was given **INVALID\_CURRENCY** an invalid currency value was given **INVALID\_TIMEZONE** an invalid timezone value was given |
| account\_id             | URL encoded string                                          | X ads account id of the linked account                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| funding\_instrument\_id | URL encoded string                                          | ID of the active partner managed funding instrument                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| signature               | URL encoded, base64 encoded binary code, as explained below | Base64 encoded HMAC-SHA1 signature that combines a shared secret and the other parameters to verify authenticity of the call, as well as validity of the parameters. To make sure the callback url is only valid for the X user\_id that the account link process was intended for, the X user\_id is to be appended to the shared secret (using &) when signing the request.                                                                                                                                                                                      |

To make sure the callback URL is only valid for the X `user_id` that the account link process was intended for, the X `user_id` is to be appended to the shared secret (using &) when signing the request.
 

#### Signing the request and callback URLs

In order to ensure that the requests to `/link_managed_account` and the callback url are valid, the requests need to be signed at the source and verified by the recipient before the recipient takes action on them. Signing the request with a secret that is shared between X and the managing partner ensures that each party only accepts requests sent by the authorized counterpart.

The signature generation algorithm is similar to the one used in OAuth.

Create a signature base string as follows:

* Convert the HTTP Method to uppercase and set the base string equal to this value.
* Append the ‘&’ character to the base string.
* Percent encode the URL (without parameters) and append it to the base string.
* Append the ‘&’ character to the base string.
* Append the percent encoded query string, which is built as follows:
* Percent encode every key and value that will be signed.
* Sort the list of parameters alphabetically by key.
* For each key/value pair (and with primary\_promotable\_user\_id for the partner redirect url):
* Append the percent encoded key to the query string.
* Append the ‘=’ character to the base string.
* Append the percent encoded value to the query string.
* Separate the percent encoded key=value pairs with the ‘&’ character.
* Use the HMAC-SHA1 algorithm, using the previously exchanged shared secret, as the key, and the base string as the value to generate the signature.
* Base64 encode the output of Step 2, drop the trailing newline character percent encode the signature generated in Step 3 and add it to the url in a signature parameter
   

#### Signing examples

Signing a link account request

Url to sign, assuming a GET request:

[https://ads.x.com/link\\\_managed\\\_account?callback\\\_url=https%3A%2F%2Fmanagingpartner.com%2Flink\\\_account\\\_callback\&amp;client\\\_app\\\_id=12345\&amp;fi\\\_description=some%20name\&amp;promotable\\\_user\\\_id=1](https://ads.x.com/link\\_managed\\_account?callback\\_url=https%3A%2F%2Fmanagingpartner.com%2Flink\\_account\\_callback\&amp;client\\_app\\_id=12345\&amp;fi\\_description=some%20name\&amp;promotable\\_user\\_id=1)

This url has the following parameters:

callback\_url = [https://managingpartner.com/link\\\_account\_callback](https://managingpartner.com/link\\_account_callback)
client\_app\_id = 12345
fi\_description = some name
promotable\_user\_id = 1

The base string consisting of http method and url without parameters, steps a - d, looks like:

GET [https://ads.x.com/link\\\_managed\\\_account](https://ads.x.com/link\\_managed\\_account)

The query string, produced by the substeps of e, looks like:

callback\_url=[https://managingpartner.com/link\\\_account\\\_callback\&client\\\_app\\\_id=12345\&fi\\\_description=some](https://managingpartner.com/link\\_account\\_callback\&client\\_app\\_id=12345\&fi\\_description=some) name\&promotable\_user\_id=1

Note that the key-value pairs are sorted by key name.

The percent encoded query string looks like:

callback\_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink\_account\_callback%26client\_app\_id%3D12345%26fi\_description%3Dsome%2520name%26promotable\_user\_id%3D1

The complete base string, combining steps a - d and e:

GET [https://ads.x.com/link\\\_managed\\\_account\&callback\\\_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink\\\_account\\\_callback%26client\\\_app\\\_id%3D12345%26fi\\\_description%3Dsome%2520name%26promotable\\\_user\\\_id%3D1](https://ads.x.com/link\\_managed\\_account\&callback\\_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink\\_account\\_callback%26client\\_app\\_id%3D12345%26fi\\_description%3Dsome%2520name%26promotable\\_user\\_id%3D1)

Using the hmac-sha1 algorithm we will sign this with the word “secret” as the key. The result is Base64 encoded, and presented without the final “\n” (steps 2 and 3): `KBxQMMSpKRrtg9aw3qxK4fTXvUc=`

This signature is then added (percent encoded) to the end of the original url in the signature parameter (step 4):

[https://ads.x.com/link\\\_managed\\\_account?callback\\\_url=https%3A%2F%2Fmanagingpartner.com%2Flink\\\_account\\\_callback\&amp;client\\\_app\\\_id=12345\&amp;fi\\\_description=some%20name\&amp;promotable\\\_user\\\_id=1\&amp;signature=KBxQMMSpKRrtg9aw3qxK4fTXvUc%3D](https://ads.x.com/link\\_managed\\_account?callback\\_url=https%3A%2F%2Fmanagingpartner.com%2Flink\\_account\\_callback\&amp;client\\_app\\_id=12345\&amp;fi\\_description=some%20name\&amp;promotable\\_user\\_id=1\&amp;signature=KBxQMMSpKRrtg9aw3qxK4fTXvUc%3D)

Signing a partner redirect url (account link request callback) The URL to sign, assuming a GET request:

[https://managingpartner.com/link\\\_account\\\_callback?status=OK\&amp;account\\\_id=ABC\&amp;funding\\\_instrument\_id=DEF](https://managingpartner.com/link\\_account\\_callback?status=OK\&amp;account\\_id=ABC\&amp;funding\\_instrument_id=DEF)

This url has the following parameters:

`account_id` = `ABC`, `funding_instrument_id` = `DEF` and `status` = `OK`

The base string consisting of http method and url without parameters, steps a - d, looks like:

GET https%3A%2F%2Fmanagingpartner.com%2Flink\_account\_callback&\`\`

The query string, produced by the substeps of e, looks like:

account\_id=ABC\&funding\_instrument\_id=DEF\&status=OK

The percent encoded query string looks like:

account\_id%3DABC%26funding\_instrument\_id%3DDEF%26status%3DOK

The complete base string, combining steps a - d and e:

GET https%3A%2F%2Fmanagingpartner.com%2Flink\_account\_callback\&account\_id%3DABC%26funding\_instrument\_id%3DDEF%26status%3DOK

Using the hmac-sha1 algorithm we will sign this with the word “secret” and the X user id for which the original link request was made, 1 (`promotable_user_id` = 1 from above) as the key, “secret&1”.

The result is Base64 encoded, and presented without the final “\n” (steps 2 and 3): `jDSHDkHJIFXpPLVxtA3a9d4bPjM=`

This signature is then added (percent encoded) to the end of the original url in the signature parameter (step 4):

[https://managingpartner.com/link\\\_account\\\_callback?\&amp;status=OK\&amp;account\\\_id=ABC\&amp;funding\\\_instrument\_id=DEF\&amp;signature=jDSHDkHJIFXpPLVxtA3a9d4bPjM%3D](https://managingpartner.com/link\\_account\\_callback?\&amp;status=OK\&amp;account\\_id=ABC\&amp;funding\\_instrument_id=DEF\&amp;signature=jDSHDkHJIFXpPLVxtA3a9d4bPjM%3D)

### Shared Key use / renewal

The signing algorithm should have the ability to repeat itself with multiple keys. This will allow multiple shared keys to be used, and enables cycling shared keys on a periodic basis.
 

### partner\_managed\_funding\_instrument creation

If the fi\_description parameter is given, and no existing partner\_managed\_funding\_instrument with the same name exists in the account, a new partner\_managed\_funding\_instrument will be created, and all existing partner\_managed\_funding\_instruments will be paused.

If a partner\_managed\_funding\_instrument with the same name exists, no new one will be created.
 

### Repeated on-boarding flow calls / token refresh

The on-boarding flow can be repeated in case the API access token was lost. The on-boarding flow implementation will require the user is logged in. If the user matches the promotable\_user\_id, and the associated ads account is found, and everything looks good, the user will be redirected back to the callback url, and the partner can initiate the OAuth flow to obtain an [access token](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow).
 

### Non-redirectable error flow

If the account link url is invoked with invalid parameters, the user will be shown a page similar to the one shown in the OAuth flow when invalid or expired parameters are given.
 

#### 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/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/reference#line-items) using the `placements` parameter. The possible values are:

* `ALL_ON_TWITTER`
* `PUBLISHER_NETWORK`
* `TWITTER_PROFILE`
* `TWITTER_SEARCH`
* `TWITTER_TIMELINE`
* `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/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.

| Objective         | `ALL_ON_TWITTER` | `TWITTER_PROFILE` | `TWITTER_SEARCH` | `TWITTER_TIMELINE` |
| :---------------- | :--------------- | :---------------- | :--------------- | :----------------- |
| `APP_ENGAGEMENTS` | ✔                | ✔                 | ✔                | ✔                  |
| `APP_INSTALLS`    | ✔                | ✔                 | ✔                | ✔                  |
| `REACH`           | ✔                | ✔                 | ✔                | ✔                  |
| `FOLLOWERS`       | ✔                | ✔                 | ✔                | ✔                  |
| `ENGAGEMENTS`     | ✔                | ✔                 | ✔                | ✔                  |
| `VIDEO_VIEWS`     | ✔                | ✔                 | ✔                | ✔                  |
| `PREROLL_VIEWS`   | ✔                | ✔                 | ✔                | ✔                  |
| `WEBSITE_CLICKS`  | ✔                | ✔                 | ✔                | ✔                  |

**Note**: It is not possible to specify *only* `TWITTER_PROFILE` placement.

**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.

### Ad groups FAQ

This document is meant to be a collection of commonly asked questions about Ad Groups in X's Ads API.

#### What is an Ad Group?

Ad groups, known as line items in the Ads API, exist under campaigns and are used for targeting and bidding against a set of X users. Advertisers promote Tweets or media (e.g., videos that are promoted as In-stream ads) by associating them with a line item.

#### How do we create an Ad Group?

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?

Ad Groups are intended to make it easier for advertisers to organize, optimize and manage their campaigns.

The advantage of Ad Groups is to compare and control different strategies across bid, budget, creative, and targeting. Upon associating multiple Promoted Tweets to a single line item, the auction would select the best Tweet from that group and then select the best Tweet for that campaign from all of the line items. If you have multiple Ad Groups with single Tweets, it would effectively select the Tweet that would likely perform better from that Ad Group.

Using Ad Groups enables an advertiser to split up targeting and bidding into a much greater number of possible combinations, and in general allows splitting up targeting into logical groups.

Ads API tools in particular could be built around fine tuned optimization rules with Ad Groups that would be more difficult to do via manual edits due to the larger scale of line item and creative combinations.

#### How does the line item budget relate to campaign budget in an Ad Groups campaign?

The total\_budget\_amount\_local\_micro for a line item cannot exceed the total budget for its parent campaign. Similarly, the line item’s bid\_amount\_local\_micro value should not exceed daily\_budget\_amount\_local\_micro or total\_budget\_amount\_local\_micro of the parent campaign. Setting these values incorrectly may put the overall campaign into a paused and unservable state.

Note that the total campaign budget can be less than the sum of the budgets of its child line items, and distribution of budget between line items is partially up to the Ads API tool to effectively optimize and change as daily performance of targeting (line item) could differ significantly day to day due to X’s realtime nature.

#### Do Ad Groups perform better than single line items?

The performance of a campaign depends upon many factors and effectively a Tweet is the final deciding factor of performance. A Line Item will be treated as a factor of whether or not a Tweet is even in the running to be served to a user.

Line items that target the same sets of users are considered to have overlap of users. It is considered a best practice to reduce this overlap of targeting between line items so that the highest performing sets of users can be clearly identified.

## Guides

### Video Views Preroll Objective

The following guide outlines the steps required to set up a PREROLL\_VIEWS campaign on the Ads API. Broadly speaking these campaigns are split into two types, Curated Categories and Content Categories (referred to as Standard Categories on the Ads UI).  

#### Endpoints Required

* [Chunked media upload](/x-api/media/quickstart/media-upload-chunked) (for video upload)
* [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)
* [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/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

#### Upload the video

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/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/reference#media-library) endpoint.

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
POST https://ads-api.x.com/8/55w3kv/media\_library?media\_key=3_931236738554519552

{
 "request": {
   "params": {
     "account_id": "55w3kv",
     "media\_key": "3\_931236738554519552"
   }
 },
 "data": {
   "tweeted": false,
   "name": null,
   "file_name": null,
   "media\_url": "https://video.twimg.com/amplify\_video/1059840836186165250/vid/568x320/Gr2l1fB1X7xotKwC.mp4?tag=8",
   "media\_category": "AMPLIFY\_VIDEO",
   "media\_key": "3\_931236738554519552",
   "created_at": "2017-11-16T19:05:14Z",
   "media\_status": "TRANSCODE\_COMPLETED",
   "media_id": 931236738554519552,
   "media_type": "VIDEO",
   "updated_at": "2017-11-16T19:05:23Z",
   "deleted": false
 }
}
```

#### Setup the campaign

### Campaign Creation

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 title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
POST https://ads-api.x.com/8/accounts/55w3kv/campaigns?name=test-curated-categories-api&funding\_instrument\_id=103hp9&start\_time=2021-02-10&entity\_status=PAUSED&daily\_budget\_amount\_local\_micro=55000000

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

### 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/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 title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
GET https://ads-api.x.com/8/advertiser\_business\_categories

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

Now, in order to set the `categories` parameter to "Science & Education", the entire set of `iab_categories` i.e., `"IAB5", "IAB15"` must be set for the line item, like so:

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
POST https://ads-api.x.com/8/accounts/55w3kv/line\_items?campaign\_id=f2rp3&bid\_amount\_local\_micro=5500000&name=curated-category-line-item&product\_type=MEDIA&placements=ALL\_ON\_TWITTER&objective=PREROLL_VIEWS&categories=IAB3,IAB13,IAB21

{
  "request": {
    "params": {
      "name": "curated-category-line-item",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 5500000,
      "product_type": "MEDIA",
      "objective": "PREROLL_VIEWS",
      "account_id": "55w3kv",
      "categories": \[
        "IAB3",
        "IAB13",
        "IAB21"
      \],
      "campaign_id": "f2rp3"
    }
  },
  "data": {
    "bid_type": "MAX",
    "advertiser\_user\_id": 312226591,
    "name": "curated-category-line-item",
    "placements": \[
      "ALL\_ON\_TWITTER"
    \],
    "start_time": null,
    "bid\_amount\_local_micro": 5500000,
    "automatically\_select\_bid": false,
    "advertiser_domain": null,
    "target\_cpa\_local_micro": null,
    "raw_categories": \[
      "x",
      "5l",
      "9z"
    \],
    "primary\_web\_event_tag": null,
    "charge\_by": "VIEW\_3S_100PCT",
    "product\_type": "PROMOTED\_TWEETS",
    "end_time": null,
    "duration\_in\_days": null,
    "bid\_unit": "VIEW\_3S_100PCT",
    "total\_budget\_amount\_local\_micro": null,
    "objective": "PREROLL_VIEWS",
    "id": "iqwka",
    "entity_status": "ACTIVE",
    "automatic\_tweet\_promotion": null,
    "optimization": "DEFAULT",
    "frequency_cap": null,
    "android\_app\_store_identifier": null,
    "categories": \[
      "IAB3",
      "IAB13",
      "IAB21"
    \],
    "currency": "USD",
    "created_at": "2021-02-09T00:00:46Z",
    "tracking_tags": \[\],
    "ios\_app\_store_identifier": null,
    "amplify_config": {
      "auto_promote": true,
      "is_open": true
    },
    "updated_at": "2021-02-09T00:00:46Z",
    "campaign_id": "f2rp3",
    "creative_source": "MANUAL",
    "deleted": false
  }
}
```

#### Publisher Selection

An advertiser may choose to target either a Content Category or a Curated Category, with additional details described below. 

**Note:**  Line items may target either Curated or Content  Categories but not both. 

### 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/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/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/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.

First, the line item’s targeting criteria is set to the value 96683cc9126741d

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
GET https://ads-api.x.com/8/targeting\_criteria/locations?country\_code=US&location_type=COUNTRIES

{
  "data": \[
    {
      "name": "United States",
      "country_code": "US",
      "location_type": "COUNTRIES",
      "targeting_value": "96683cc9126741d1",
      "targeting_type": "LOCATION"
    }
  \],
  "request": {
    "params": {
      "location_type": "COUNTRIES",
      "country_code": "US"
    }
  },
  "next_cursor": null
}

POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
\[
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwka",
      "targeting_type": "LOCATION",
      "targeting_value": "96683cc9126741d1",
      "operator_type": "EQ"
    }
  }
\]

{
  "data": \[
    {
      "line\_item\_id": "iqwka",
      "name": "United States",
      "raw_negated": false,
      "raw\_targeting\_value": "2",
      "id": "rv9hmc",
      "raw\_targeting\_type": "GEO",
      "raw\_operator\_type": "EQUAL_TO",
      "location_type": "COUNTRIES",
      "operator_type": "EQ",
      "created_at": "2021-02-09T00:06:28Z",
      "targeting_value": "96683cc9126741d1",
      "updated_at": "2021-02-09T00:06:28Z",
      "deleted": false,
      "targeting_type": "LOCATION"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwka",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "96683cc9126741d1",
        "targeting_type": "LOCATION"
      },
      "operation_type": "Create"
    }
  \]
}

POST https://ads-api.x.com/8/accounts/55w3kv/line\_item\_curated\_categories?line\_item\_id=iqwka&curated\_category_id=9ddrgesiap6o

{
  "request": {
    "params": {
      "curated\_category\_id": "9ddrgesiap6o",
      "line\_item\_id": "iqwka",
      "account_id": "55w3kv"
    }
  },
  "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
  }
}
```

### Content Categories

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>
  **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. 
</Note>

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
GET https://ads-api.x.com/8/content_categories
{
      "name": "News & Current Events",
      "id": "sr",
      "iab_categories": \[
        "IAB12",
        "IAB14"
      \],
      "publishers\_in\_last\_thirty\_days": 124,
      "videos\_monetized\_in\_last\_thirty_days": 5429
    }
}

POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
\[
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwls",
      "targeting\_type": "IAB\_CATEGORY",
      "targeting_value": "IAB12",
      "operator_type": "EQ"
    }
  },
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwls",
      "targeting\_type": "IAB\_CATEGORY",
      "targeting_value": "IAB14",
      "operator_type": "EQ"
    }
  }
\]

{
  "data": \[
    {
      "line\_item\_id": "iqwls",
      "name": "News",
      "raw_negated": false,
      "raw\_targeting\_value": "5h",
      "id": "saib9p",
      "raw\_targeting\_type": "IAB_CATEGORY",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "EQ",
      "created_at": "2021-03-30T17:35:50Z",
      "targeting_value": "IAB12",
      "updated_at": "2021-03-30T17:35:50Z",
      "deleted": false,
      "targeting\_type": "IAB\_CATEGORY"
    },
    {
      "line\_item\_id": "iqwls",
      "name": "Society",
      "raw_negated": false,
      "raw\_targeting\_value": "5y",
      "id": "saib9q",
      "raw\_targeting\_type": "IAB_CATEGORY",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "EQ",
      "created_at": "2021-03-30T17:35:50Z",
      "targeting_value": "IAB14",
      "updated_at": "2021-03-30T17:35:50Z",
      "deleted": false,
      "targeting\_type": "IAB\_CATEGORY"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwls",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "IAB12",
        "targeting\_type": "IAB\_CATEGORY"
      },
      "operation_type": "Create"
    },
    {
      "params": {
        "line\_item\_id": "iqwls",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "IAB14",
        "targeting\_type": "IAB\_CATEGORY"
      },
      "operation_type": "Create"
    }
  \]
}
```

##### Associate the account media (video) with the line item

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 title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
POST https://ads-api.x.com/8/accounts/55w3kv/media_creatives
line\_item\_id=4bii5&account\_media\_id=knb

{
 "data":{
   "account\_media\_id":"74g",
   "approval_status":"ACCEPTED",
   "created_at":"2016-02-11T22:23:23Z",
   "deleted":false,
   "id":"qeq",
   "landing_url":null,
   "line\_item\_id":"4bii5",
   "serving_status":"ACTIVE",
   "updated_at":"2016-02-11T22:23:23Z"
 },
 "request":{
   "params":{
     "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/reference#preroll-call-to-actions) endpoint allows you to control the button CTA and the destination URL.

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
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

{
 "data":{
   "id":"aaa111",
   "line\_item\_id":"4bii5",
   "call\_to\_action":"WATCH_NOW",
   "call\_to\_action_url":"https://x.com/AdsAPI",
   "created_at":"2016-02-11T22:23:23Z",
   "updated_at":"2016-02-11T22:23:23Z",
   "deleted":false
 },
 "request":{
   "params":{
     "line\_item\_id":"4bii5",
     "call\_to\_action":"VISIT_SITE",
     "call\_to\_action_url":"https://x.com/AdsAPI"
   }
 }
}
```

#### Set targeting criteria

The targeting criterion utilized for pre-roll video ads is only available 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/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 title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
\[
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwls",
      "targeting\_type": "CONTENT\_PUBLISHER_ID",
      "targeting_value": "1917731",
      "operator_type": "NE"
    }
  }
\]

{
  "data": \[
    {
      "line\_item\_id": "iqwka",
      "name": "realsaltlake",
      "raw_negated": true,
      "raw\_targeting\_value": "aajwo",
      "id": "sajk32",
      "raw\_targeting\_type": "CONTENT_PUBLISHER",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "NE",
      "created_at": "2021-03-30T18:02:32Z",
      "targeting_value": 17288520,
      "updated_at": "2021-03-30T18:02:32Z",
      "deleted": false,
      "targeting\_type": "CONTENT\_PUBLISHER_USER"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwka",
        "account_id": "55w3kv",
        "operator_type": "NE",
        "targeting_value": "17288520",
        "targeting\_type": "CONTENT\_PUBLISHER_USER"
      },
      "operation_type": "Create"
    }
  \]
}
```

#### 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/reference#put-accounts-account-id-line-items-line-item-id).

PUT [https://ads-api.x.com/8/accounts/55w3kv/campaigns/f2rp3](https://ads-api.x.com/8/accounts/55w3kv/campaigns/f2rp3)?
entity\_status=ACTIVE

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "campaign_id": "f2rp3",
      "account_id": "55w3kv"
    }
  },
  "data": {
    "name": "test-curated-categories-api",
    "start_time": "2021-02-10T00:00:00Z",
    "reasons\_not\_servable": \[
    \],
    "servable": false,
    "purchase\_order\_number": null,
    "effective_status": "ACTIVE",
    "daily\_budget\_amount\_local\_micro": 55000000,
    "end_time": null,
    "funding\_instrument\_id": "103hp9",
    "duration\_in\_days": null,
    "standard_delivery": true,
    "total\_budget\_amount\_local\_micro": null,
    "id": "f2rp3",
    "entity_status": "ACTIVE",
    "frequency_cap": null,
    "currency": "USD",
    "created_at": "2021-02-08T23:55:38Z",
    "updated_at": "2021-02-08T23:55:38Z",
    "deleted": false
  }
}
```

#### Analytics

Analytics for `VIDEO_VIEWS_PREROLL` campaigns are available using our stats endpoints.

### Keyword Targeting in Timelines

Keyword targeting is fundamental to our Promoted Tweets products, giving campaigns better reach. Keyword targeting in timeline enables platforms to target X users based on keywords in their recent Tweets. For example, if an advertiser is targeting the unordered keyword combination “plan + trip”, and a user Tweets, “I’m starting to plan my trip to Cabo, any suggestions?” while the campaign is running, that user may soon afterward see the advertiser’s Promoted Tweet.

#### How does it work?

TL;DR: from an API standpoint, this change is quite simple: you can now target keywords on Promoted Tweets in Timeline. Just set the `targeting_type` to `unordered_keywords` or `phrase_keywords` for line items.

#### Quick Start Guide

* Create a new line item with the placement set to include either `ALL_ON_TWITTER` or `TWITTER_TIMELINE` [POST accounts/:account\_id/line\_items](https://dev.x.com/ads/reference/post/accounts/%3Aaccount_id/line_items)
* 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)

***

## Full API Reference

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.


# Campaign Management API Reference
Source: https://docs.x.com/x-ads-api/campaign-management/reference

Endpoint reference for the X Ads Campaign Management API covering accounts, campaigns, line items, funding instruments, and targeting criteria requests.

## API Reference

<Note>
  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
  <a href="/x-ads-api/campaign-management">Campaign Management Overview</a>.
</Note>

### Accounts

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  Scope the response to just the desired account IDs by specifying a comma-separated list of identifiers.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.
  <br />Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  An optional query to scope resource by `name`. Performs case-insensitive prefix matching.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.
  <br /><br />**Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

```json theme={null}
GET https://ads-api.x.com/12/accounts?account_ids=18ce54d4x5t
```

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
       {
         "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
       {
         "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.

<Note type="warning">
  **SANDBOX ONLY**
</Note>

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api-sandbox.x.com/12/accounts`

**Parameters**

None

**Example Request**

`POST https://ads-api-sandbox.x.com/12/accounts`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
       {
         "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The name of the account.
</ParamField>

<ParamField type="string">
  Industry that the account is associated with.
  <br /><br />Possible values: `AGENCY`, `BUSINESS_TO_BUSINESS`, `ONLINE_SERVICES`, `EDUCATION`, `FINANCIAL`, `HEALTH`, `GOVERNMENT`, `MEDIA`, `MOBILE`, `RESTAURANT`, `RETAIL`, `TECHNOLOGY`, `TRAVEL`, `OTHER`
</ParamField>

**Example Request**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t?name='API McTestface 2'&industry_type=TECHNOLOGY`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
       {
         "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 type="warning">
  **SANDBOX ONLY**
</Note>

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

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

**Example Request**

`DELETE https://ads-api-sandbox.x.com/12/accounts/gq12fh`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
       {
         "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")**

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request. Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.
  <br /><br />**Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_apps`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
       {
         "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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 type="warning">
  This endpoint is currently in beta and requires allowlisting.
</Note>

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/account_history`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  The entity type to retrieve data for.<br /><br />
  Possible values: `CAMPAIGN`, `LINE_ITEM`, `PROMOTED_TWEET`, `TARGETING_CRITERIA`, `PROMOTED_ACCOUNT`
</ParamField>

<ParamField type="string">
  The specific entity to retrieve data for.
</ParamField>

<ParamField type="string">
  Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />
  **Note**: Must be expressed in whole hours (0 minutes and 0 seconds).
</ParamField>

<ParamField type="string">
  Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />
  **Note**: Must be expressed in whole hours (0 minutes and 0 seconds).
</ParamField>

<ParamField type="long">
  Scopes the response to a specific user.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_history?entity_type=CAMPAIGN&entity_id=fc3h5&count=1`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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.
</Note>

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

`GET https://ads-api.x.com/12/advertiser_business_categories`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="array">
  An array of targeting criteria objects. A list of required and optional targeting criteria parameters are available on the POST targeting criteria endpoint.
</ParamField>

<ParamField type="string">
  Specify the relationship that the targeting criterion should have. For example, to set negated targeting, use `operator_type=NE`.<br /><br />
  Possible values: `EQ`, `NE`
</ParamField>

**Example Request**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/audience_estimate`

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
        "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**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "targeting_criteria": null,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "audience_size": {
          "min": 38236294,
          "max": 42261167
        }
      }
    }
```

### Authenticated User Access

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/authenticated_user_access`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "data": {
        "user_id": "2417045708",
        "permissions": [
          "ACCOUNT_ADMIN",
          "TWEET_COMPOSER"
        ]
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      }
    }
```

### Bidding Rules

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  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.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/bidding_rules?currency=USD`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  An optional query to scope resource by `name`.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include draft campaigns results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "campaign_ids": [
            "8wku2"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "test",
          "budget_optimization": "LINE_ITEM",
          "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": null,
          "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the campaign you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "campaign_id": "8wku2",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "LINE_ITEM",
        "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": null,
        "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The identifier for the funding instrument to create the campaign under.
</ParamField>

<ParamField type="string">
  The name for the campaign. Maximum length: 255 characters.
</ParamField>

<ParamField type="string">
  Select the type of budget optimization to be applied.<br /><br />
  Possible values: `LINE_ITEM`
</ParamField>

<ParamField type="long">
  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.<br /><br />
  **Note**: This should be less than or equal to the `total_budget_amount_local_micro` and is required for most Funding Instrument types.
</ParamField>

<ParamField type="string">
  The campaign status.<br /><br />
  Possible values: `ACTIVE`, `DRAFT`, `PAUSED`
</ParamField>

<ParamField type="string">
  The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters.
</ParamField>

<ParamField type="boolean">
  **Deprecated at the campaign level.** Since budget optimization is always `LINE_ITEM`, standard versus accelerated delivery is configured on the line item via its `standard_delivery` parameter. See [Budget Pacing](/x-ads-api/campaign-management#budget-pacing) for more information.
</ParamField>

<ParamField type="long">
  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.
</ParamField>

**Example Request**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?funding_instrument_id=lygyi&name=demo&daily_budget_amount_local_micro=140000000&entity_status=PAUSED&budget_optimization=LINE_ITEM`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "name": "demo",
          "budget_optimization": "LINE_ITEM",
          "daily_budget_amount_local_micro": 140000000,
          "funding_instrument_id": "lygyi",
          "entity_status": "PAUSED",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "demo",
        "budget_optimization": "LINE_ITEM",
        "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": null,
        "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`

<ParamField type="string">
  The per item operation type being performed.<br /><br />
  Possible values: `Create`, `Delete`, `Update`
</ParamField>

<ParamField type="object">
  A JSON object containing all the parameters for the campaign objects. For a list of required and optional campaign parameters, see the single POST endpoint above.
</ParamField>

**Example Request**

`POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/campaigns`

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    [
      {
        "operation_type":"Create",
        "params":{
          "name":"batch campaigns",
          "funding_instrument_id":"lygyi",
          "daily_budget_amount_local_micro":140000000,
          "entity_status":"PAUSED",
          "budget_optimization":"LINE_ITEM"
        }
      }
    ]
```

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "data": [
        {
          "name": "batch campaigns",
          "budget_optimization": "LINE_ITEM",
          "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": null,
          "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":"LINE_ITEM",
            "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the campaign you are operating with in the request.
</ParamField>

<ParamField type="string">
  Select the type of budget optimization to be applied.<br /><br />
  Possible values: `LINE_ITEM`
</ParamField>

<ParamField type="long">
  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.<br /><br />
  **Note**: This should be less than or equal to the `total_budget_amount_local_micro`.
</ParamField>

<ParamField type="string">
  The campaign status.<br /><br />
  Possible values: `ACTIVE`, `PAUSED`
</ParamField>

<ParamField type="string">
  The name for the campaign. Maximum length: 255 characters.
</ParamField>

<ParamField type="string">
  The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters.
</ParamField>

<ParamField type="boolean">
  **Deprecated at the campaign level.** Since budget optimization is always `LINE_ITEM`, standard versus accelerated delivery is configured on the line item via its `standard_delivery` parameter. See [Budget Pacing](/x-ads-api/campaign-management#budget-pacing) for more information.
</ParamField>

<ParamField type="long">
  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.
</ParamField>

**Example Request**

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

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "campaign_id": "8wku2",
          "daily_budget_amount_local_micro": 140000000,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "LINE_ITEM",
        "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": null,
        "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the campaign you are operating with in the request.
</ParamField>

**Example Request**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8yn7m`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "campaign_id": "8yn7m",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "LINE_ITEM",
        "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": null,
        "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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**

`GET https://ads-api.x.com/12/content_categories`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories?country_codes=US`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the Curated Category you are operating with in the request.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories/9ddrgesiap6o`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  An optional parameter that enables querying for a specific feature key. Requests may include multiple comma-separated keys.<br /><br />
  **Note**: Only the features that are accessible by this account will be included in the response.<br /><br />
  Possible values: `REACH_AND_FREQUENCY_ANALYTICS`, `REACH_FREQUENCY_CAP`, `WEBSITE_CLICKS_CPM_BILLING`
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/features`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A comma-separated list of account features to add to the account.<br /><br />
  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`
</ParamField>

**Example Request**

`POST https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=VALIDATED_AGE_TARGETING`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A comma-separated list of account features to remove from the account.<br /><br />
  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`
</ParamField>

**Example Request**

`DELETE https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=PREROLL_VIEWS_OBJECTIVE`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request. Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the funding instrument you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments/lygyi`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The currency, expressed in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217).
</ParamField>

<ParamField type="string">
  The date for the funding instrument to become active and usable, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
</ParamField>

<ParamField type="string">
  The type of funding instrument to create.<br /><br />
  Possible values: `AGENCY_CREDIT_LINE`, `CREDIT_CARD`, `CREDIT_LINE`, `INSERTION_ORDER`, `PARTNER_MANAGED`
</ParamField>

<ParamField type="string">
  The date for the funding instrument to become inactive, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
</ParamField>

<ParamField type="long">
  The total credit available against this funding instrument.<br /><br />
  **Note**: Only applicable to some funding instrument types.
</ParamField>

<ParamField type="long">
  The total budget amount allocated to this funding instrument.<br /><br />
  **Note**: Only applicable to some funding instrument types.
</ParamField>

**Example Request**

`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**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the funding instrument you are operating with in the request.
</ParamField>

**Example Request**

`DELETE https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments/hxt82`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of categories. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/iab_categories?count=2`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="string">
  An optional query to scope resource by `name`.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include draft campaigns results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?line_item_ids=itttx`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/itttx`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The identifier for the campaign to create the line item under.
</ParamField>

<ParamField type="string">
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will stop serving.
</ParamField>

<ParamField type="string">
  The campaign objective for this line item.<br /><br />
  Possible values: `APP_ENGAGEMENTS`, `APP_INSTALLS`, `REACH`, `FOLLOWERS`, `ENGAGEMENTS`, `VIDEO_VIEWS`, `PREROLL_VIEWS`, `WEBSITE_CLICKS`
</ParamField>

<ParamField type="string">
  The placement location(s) for this line item to display in. Specify a comma-separated list of placement values.<br /><br />
  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`
</ParamField>

<ParamField type="string">
  The type of promoted product that this line item will contain.<br /><br />
  Possible values: `MEDIA`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEETS`
</ParamField>

<ParamField type="string">
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.
</ParamField>

<ParamField type="string">
  The website domain for this advertiser, without the protocol specification.<br /><br />
  **Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.
</ParamField>

<ParamField type="string">
  The Google App Store identifier for promoted applications.<br /><br />
  **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`.
</ParamField>

<ParamField type="long">
  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.<br /><br />
  **Note**: Required if `bid_strategy` is set to either `MAX` or `TARGET`. Only values greater than zero are accepted.
</ParamField>

<ParamField type="string">
  The relevant IAB categories for this advertiser. See [GET iab\_categories](/x-ads-api/campaign-management/reference#iab-categories).<br /><br />
  **Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.
</ParamField>

<ParamField type="string">
  The numeric portion of the Apple App Store identifier for promoted applications.<br /><br />
  **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`.
</ParamField>

<ParamField type="string">
  The identifier of the primary web event tag. Allows more accurate tracking of engagements for the campaign pertaining to this line item.<br /><br />
  **Note**: Required when the line item's goal is set to `WEBSITE_CONVERSIONS`.
</ParamField>

<ParamField type="string">
  The X user identifier for the handle promoting a `PREROLL_VIEWS` ad. Only certain client applications may use this parameter.
</ParamField>

<ParamField type="string">
  Used to expand the reach of campaigns by targeting users similar to those already targeted.<br /><br />
  **Note**: By default, no expansion will be applied.<br /><br />
  Possible values: `BROAD`, `DEFINED`, `EXPANDED`
</ParamField>

<ParamField type="string">
  The bidding mechanism.<br /><br />
  `AUTO` automatically optimizes bidding based on daily budget and campaign flight dates.<br />
  `MAX` sets the maximum allowable bid and is **not** available when the objective is set to `REACH` or `FOLLOWERS`.<br />
  `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`.<br /><br />
  **Note**: If set to `AUTO`, `bid_amount_local_micro` will be ignored.<br />
  **Note**: Default based on objective.<br /><br />
  Possible values: `AUTO`, `MAX`, `TARGET`
</ParamField>

<ParamField type="int">
  The time period within which the `frequency_cap` is achieved.<br /><br />
  Possible values: `1`, `7`, `30`
</ParamField>

<ParamField type="string">
  The line item status.<br /><br />
  Possible values: `ACTIVE`, `DRAFT`, `PAUSED`
</ParamField>

<ParamField type="int">
  The maximum number of times an ad could be delivered to a user.<br /><br />
  **Note**: Only supported for `REACH`, `ENGAGEMENTS`, `VIDEO_VIEWS`, and `PREROLL_VIEWS` objectives.
</ParamField>

<ParamField type="string">
  The optimization setting to use with this line item.<br /><br />
  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).<br /><br />
  The `SITE_VISITS` option is only available with the `WEBSITE_CLICKS` objective.<br /><br />
  **Note**: Default based on objective.<br /><br />
  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`
</ParamField>

<ParamField type="string">
  The name for the line item.<br /><br />
  Min, Max length: 1, 255
</ParamField>

<ParamField type="string">
  The unit to charge this line item by. This setting can only be modified for line items using the `APP_INSTALLS` objective.<br /><br />
  **Note**: The default `pay_by` is automatically set based upon the campaign objective and line item's bid unit.<br /><br />
  The `APP_INSTALLS` goal supports both `APP_CLICK` and `IMPRESSION` values. `IMPRESSION` is the default value.<br />
  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`.<br />
  The `SITE_VISITS` goal supports `IMPRESSION` values.<br /><br />
  Possible values: `APP_CLICK`, `IMPRESSION`, `LINK_CLICK`
</ParamField>

<ParamField type="boolean">
  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.
</ParamField>

<ParamField type="long">
  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.
</ParamField>

<ParamField type="long">
  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.<br /><br />
  **Note**: This should be less than or equal to the `total_budget_amount_local_micro`.
</ParamField>

**Example Request**

`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**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The per item operation type being performed.<br /><br />
  Possible values: `Create`, `Delete`, `Update`
</ParamField>

<ParamField type="object">
  A JSON object containing all the parameters for the line item objects. For a list of required and optional line item parameters, see the single POST endpoint above.
</ParamField>

**Example Request**

`POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/line_items`

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    [
      {
        "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**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField type="string">
  The website domain for this advertiser, without the protocol specification.<br /><br />
  **Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.
</ParamField>

<ParamField type="string">
  The Twitter user identifier for the handle promoting a `PREROLL_VIEWS` ad. Only certain client applications may use this parameter.
</ParamField>

<ParamField type="string">
  The Google App Store identifier for the promoted application.<br /><br />
  **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`.
</ParamField>

<ParamField type="string">
  Used to expand the reach of campaigns by targeting users similar to those already targeted.<br /><br />
  Possible values: `BROAD`, `DEFINED`, `EXPANDED`
</ParamField>

<ParamField type="long">
  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.<br /><br />
  **Note**: Required if `bid_strategy` is set to either `MAX` or `TARGET`. Only values greater than zero are accepted.
</ParamField>

<ParamField type="string">
  The bidding mechanism.<br /><br />
  `AUTO` automatically optimizes bidding based on daily budget and campaign flight dates.<br />
  `MAX` sets the maximum allowable bid and is **not** available when the objective is set to `REACH` or `FOLLOWERS`.<br />
  `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`.<br /><br />
  **Note**: If set to `AUTO`, `bid_amount_local_micro` will be ignored.<br />
  **Note**: Default based on objective.<br /><br />
  Possible values: `AUTO`, `MAX`, `TARGET`
</ParamField>

<ParamField type="string">
  The relevant IAB categories for this advertiser. See [GET iab\_categories](/x-ads-api/campaign-management/reference#iab-categories).<br /><br />
  **Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.
</ParamField>

<ParamField type="int">
  The time period within which the `frequency_cap` is achieved.<br /><br />
  Possible values: `1`, `7`, `30`
</ParamField>

<ParamField type="string">
  The line item status.<br /><br />
  Possible values: `ACTIVE`, `PAUSED`
</ParamField>

<ParamField type="string">
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will stop serving.
</ParamField>

<ParamField type="int">
  The maximum number of times an ad could be delivered to a user.<br /><br />
  **Note**: Only supported for `REACH`, `ENGAGEMENTS`, `VIDEO_VIEWS`, and `PREROLL_VIEWS` objectives.
</ParamField>

<ParamField type="string">
  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).<br /><br />
  **Note**: Default based on objective.<br /><br />
  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`
</ParamField>

<ParamField type="string">
  The numeric portion of the Apple App Store identifier for promoted applications.<br /><br />
  **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`.
</ParamField>

<ParamField type="string">
  The name for the line item.
</ParamField>

<ParamField type="string">
  The unit to charge this line item by. This setting can only be modified for line items using the `APP_INSTALLS` objective.<br /><br />
  **Note**: The default `pay_by` is automatically set based upon the campaign objective and line item's bid unit.<br /><br />
  The `APP_INSTALLS` goal supports both `APP_CLICK` and `IMPRESSION` values. `IMPRESSION` is the default value.<br />
  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`.<br />
  The `SITE_VISITS` goal supports `IMPRESSION` values.<br /><br />
  Possible values: `APP_CLICK`, `IMPRESSION`, `LINK_CLICK`
</ParamField>

<ParamField type="string">
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.
</ParamField>

<ParamField type="long">
  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.
</ParamField>

<ParamField type="long">
  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.<br /><br />
  **Note**: This should be less than or equal to the `total_budget_amount_local_micro`.
</ParamField>

**Example Request**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9cqi0?bid_amount_local_micro=140000`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the line item you are operating with in the request.
</ParamField>

**Example Request**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9f2ix`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the line item curated category you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories/yav`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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  <br />`required`           | The identifier 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.<br /><br />Type: string<br /><br />Example: `18ce54d4x5t` |
| curated\_category\_id  <br />`required` | A reference to the curated category entity you are operating with in the request.<br /><br />Type: string<br /><br />Example: `10miy`                                                                                                                                                                                                                               |
| line\_item\_id  <br />`required`        | A reference to the line item you are operating with in the request.<br /><br />Type: string<br /><br />Example: `8v7jo`                                                                                                                                                                                                                                             |

**Example Request**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories?line_item_id=iqwka&curated_category_id=9ddrgesiap6o`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the line item curated category you are operating with in the request.
</ParamField>

\| curated\_category\_id  <br />`optional` | A reference to the curated category entity you are operating with in the request.<br /><br />Type: string<br /><br />Example: `10miy` |
\| line\_item\_id  <br />`optional` | A reference to the line item you are operating with in the request.<br /><br />Type: string<br /><br />Example: `8v7jo` |

**Example Request**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq?curated_category_id=8tujl1p3yn0g`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the line item curated category you are operating with in the request.
</ParamField>

**Example Request**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="enum">
  Scope the response to just the valid placements for the specified product type.<br /><br />
  Possible values: `MEDIA`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEETS`
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/line_items/placements?product_type=PROMOTED_ACCOUNT`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "data": [
        {
          "product_type": "PROMOTED_ACCOUNT",
          "placements": [
            [
              "ALL_ON_TWITTER"
            ],
            [
              "TWITTER_TIMELINE"
            ]
          ]
        }
      ],
      "request": {
        "params": {
          "product_type": "PROMOTED_ACCOUNT"
        }
      }
    }
```

### Media Creatives

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  Scope the response to just the media creatives associated with the specified campaign.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired media creatives by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?media_creative_ids=1bzq3`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the media creative you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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/reference#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/reference#account-media) endpoint.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/media_creatives`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the account media entity you are operating with in the request.
</ParamField>

<ParamField type="string">
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField type="string">
  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/reference#post-accounts-account-id-preroll-call-to-actions) endpoint.<br /><br />
  **Note**: Required when the line item's objective is set to `WEBSITE_CLICKS`.
</ParamField>

**Example Request**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?line_item_id=8v7jo&account_media_id=10miy`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the media creative you are operating with in the request.
</ParamField>

**Example Request**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired promoted accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the promoted account you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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, an HTTP 400 `INCOMPATIBLE_LINE_ITEM` error will be returned. If the specified user is ineligible for promotion, an 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField type="long">
  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.
</ParamField>

**Example Request**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?line_item_id=9bpb2&user_id=756201191646691328`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={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
      },
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The identifier refers to the instance of a Promoted Account associated with a line item.
</ParamField>

**Example Request**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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/reference#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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?promoted_tweet_ids=1efwlo`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the promoted Tweet you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1efwlo`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField type="string">
  A comma-separated list of identifiers corresponding to specific Tweets. Up to 50 IDs may be provided.
</ParamField>

**Example Request**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?line_item_id=8v7jo&tweet_ids=822333526255120384`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

**Example Request**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1gp8a5`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired promotable users by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  A reference to the promotable user you are operating on within the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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**

`GET https://ads-api.x.com/12/publishers`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/369a02c0adc626ff6a06#?env%5BTwitter%20Ads%20API%5D=W3sia2V5IjoiYWNjb3VudF9pZCIsInZhbHVlIjoieW91cl9hZHNfYWNjb3VudF9pZCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidmVyc2lvbiIsInZhbHVlIjoiNSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfa2V5IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX2tleSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfc2VjcmV0IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX3NlY3JldCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYWNjZXNzX3Rva2VuIiwidmFsdWUiOiJ5b3VyX2FjY2Vzc190b2tlbiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidG9rZW5fc2VjcmV0IiwidmFsdWUiOiJ5b3VyX3Rva2VuX3NlY3JldCIsImVuYWJsZWQiOnRydWV9XQ==">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the recommendation ID you are operating within the request.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations/62ce8zza1q0w`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
    "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?scheduled_promoted_tweet_ids=1xboq`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the scheduled promoted Tweet you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xboq`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField type="long">
  A reference to the scheduled Tweet you are operating with in the request.
</ParamField>

**Example Request**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?line_item_id=8xdpe&scheduled_tweet_id=870358555227860992`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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_promoted_tweets/:scheduled_promoted_tweet_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

**Example Request**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xtfl`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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.

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired targeting criteria by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_ids=8u94t`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the targeting criterion you are operating with in the request.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField type="enum">
  Specify the relationship that the targeting criterion should have. For example, to exclude keywords, use `operator_type=NE`.<br /><br />
  Possible values: `EQ`, `NE`, `GTE`, `LT`
</ParamField>

<ParamField type="string">
  The type of targeting that will be applied to this line item.<br /><br />
  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`.<br /><br />
  **Note**: It is only possible to target a single `AGE` bucket per line item.<br /><br />
  Possible keyword-based values include: `BROAD_KEYWORD`, `EXACT_KEYWORD`, `PHRASE_KEYWORD`, `UNORDERED_KEYWORD`.<br /><br />
  Possible custom audience values include: `CUSTOM_AUDIENCE`, `CUSTOM_AUDIENCE_EXPANDED`.<br /><br />
  Possible installed app store category values: `APP_STORE_CATEGORY`, `APP_STORE_CATEGORY_LOOKALIKE`.<br /><br />
  Possible Twitter Audience Platform (TAP) app exclusion: `APP_LIST` (may only be used with `operator_type=NE`).
</ParamField>

<ParamField type="string">
  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.
</ParamField>

**Example Request**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_id=619jl&targeting_type=BROAD_KEYWORD&targeting_value=technology`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="enum">
  The per item operation type being performed.<br /><br />
  Possible values: `Create`, `Delete`
</ParamField>

<ParamField type="object">
  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).<br /><br />
  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.
</ParamField>

**Example Request**

`POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/targeting_criteria`

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    [
      {
        "operation_type":"Create",
        "params":{
          "line_item_id":"6f9an",
          "targeting_type":"LOCATION",
          "targeting_value":"5122804691e5fecc"
        }
      },
      {
        "operation_type":"Delete",
        "params":{
          "targeting_criterion_id":"al2rua"
        }
      }
    ]
```

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the targeting criterion you are operating with in the request.
</ParamField>

**Example Request**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/dpl3a6`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

* [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`

<ParamField type="string">
  An optional query to scope a targeting criteria. Omit this parameter to retrieve all.
</ParamField>

<ParamField type="enum">
  Scope the results by a specific app store.<br /><br />
  Possible values: `ANDROID`, `IOS`
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/targeting_criteria/app_store_categories?q=music&os_type=IOS`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="enum">
  An optional query to scope to a certain conversation type.<br /><br />
  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`
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/targeting_criteria/conversations?count=2`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  An optional query to scope a targeting criteria. Omit this parameter to retrieve all.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/targeting_criteria/devices?count=2&q=iphone`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="enum">
  An optional query to scope to certain event types.<br /><br />
  Possible values: `CONFERENCE`, `HOLIDAY`, `MUSIC_AND_ENTERTAINMENT`, `OTHER`, `POLITICS`, `RECURRING`, `SPORTS`
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the campaign will end.
</ParamField>

<ParamField type="string">
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.<br /><br />
  **Note**: Defaults to the current time.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/targeting_criteria/events?count=1`

**Example Response**

```json title="HOLIDAY" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  An optional query to scope a targeting criteria. Omit this parameter to retrieve all.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/targeting_criteria/interests?q=books`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  An optional query to scope a targeting criteria. Omit this parameter to retrieve all.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/targeting_criteria/languages?q=english`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="enum">
  Scope the results by a specific kind of location. More granular targeting than `COUNTRIES` may not be available in all locations.<br /><br />
  Possible values: `COUNTRIES`, `REGIONS`, `METROS`, `CITIES`, `POSTAL_CODES`
</ParamField>

<ParamField type="string">
  An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/targeting_criteria/locations?location_type=CITIES&q=los angeles`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/targeting_criteria/network_operators?count=5&country_code=US`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/targeting_criteria/platform_versions`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
        "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`

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/targeting_criteria/platforms`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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**

`GET https://ads-api.x.com/12/targeting_criteria/tv_markets`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  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-targeting-criteria-tv-markets).
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 50
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/targeting_criteria/tv_shows?locale=en-US&q=news&count=1`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="enum">
  Specify the type of suggestions to return.<br /><br />
  Possible values: `KEYWORD`, `USER_ID`
</ParamField>

<ParamField type="string">
  Comma separated collection of either keywords or user IDs used to seed the suggestions.<br /><br />
  **Note**: These two types of suggestions cannot be mixed.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 50
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_suggestions?suggestion_type=KEYWORD&targeting_values=developers&count=2"`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The city for the account owner's address.
</ParamField>

<ParamField type="string">
  The two-letter country code for the account owner's address.
</ParamField>

<ParamField type="string">
  The email associated with the account owner's address.
</ParamField>

<ParamField type="string">
  The first name for the account owner's address.
</ParamField>

<ParamField type="string">
  The last name for the account owner's address.
</ParamField>

<ParamField type="string">
  The company name for the account owner's address.
</ParamField>

<ParamField type="string">
  The postal code for the account owner's address.
</ParamField>

<ParamField type="string">
  The region for the account owner's address.
</ParamField>

<ParamField type="string">
  The street line for the account owner's address.
</ParamField>

<ParamField type="string">
  The second street line for the account owner's address.
</ParamField>

<ParamField type="enum">
  The entity that is billed.<br /><br />
  Possible values: `ADVERTISER`, `AGENCY`
</ParamField>

<ParamField type="enum">
  Whether the account is owned by the advertiser or by the agency.<br /><br />
  Possible values: `AGENCY`, `SELF`
</ParamField>

<ParamField type="string">
  The city for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField type="string">
  The two-letter country code for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField type="string">
  The email associated with the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField type="string">
  The first name for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField type="string">
  The last name for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField type="string">
  The company name for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField type="string">
  The postal code for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField type="string">
  The region for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField type="string">
  The street line for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField type="string">
  The second street line for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField type="enum">
  Invoice jurisdiction.<br /><br />
  Possible values: `LOI_SAPIN`, `NONE`, `NOT_SET`
</ParamField>

<ParamField type="enum">
  Whether the taxation should be individual or business.<br /><br />
  Possible values: `BUSINESS_NO_VAT`, `BUSINESS_WITH_VAT`, `INDIVIDUAL`
</ParamField>

<ParamField type="string">
  VAT exemption ID.
</ParamField>

<ParamField type="string">
  VAT registration ID.
</ParamField>

**Example Request**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings?address_name=ABC, Co.`

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired tracking tags by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?tracking_tag_ids=3m82`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the tracking tag you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField type="enum">
  The type of tracking tag.<br /><br />
  Possible value: `IMPRESSION_TAG`, `CLICK_TRACKER`
</ParamField>

<ParamField type="string">
  The tracking tag url provided by the tracking partner.
</ParamField>

**Example Request**

`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**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The tracking tag url provided by the tracking partner.
</ParamField>

**Example Request**

`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**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the tracking tag you are operating with in the request.
</ParamField>

**Example Request**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

([https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87](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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="long">
  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.
</ParamField>

**Example Request**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328`

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
      {
        "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`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="long">
  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.
</ParamField>

<ParamField type="string">
  Email to use for account notifications.
</ParamField>

<ParamField type="string">
  Contact phone number.
</ParamField>

<ParamField type="string">
  Extension for contact `contact_phone`.
</ParamField>

**Example Request**

`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**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
      {
        "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": ""
        }
      }
```


# Catalog Management
Source: https://docs.x.com/x-ads-api/catalog-management

Set up product catalogs, manage products in bulk, create product sets for targeting, and configure scheduled feeds for Dynamic Product Ads on X.

**Programmatically manage product catalogs, products, product sets, and scheduled feeds for Dynamic Product Ads.**

## Quick links

* [Full API Reference](/x-ads-api/catalog-management/reference) — All Catalog Management endpoints and objects
* [Product Specifications Guide](https://business.x.com/en/help/shopping-specs.html) — Detailed product feed requirements and best practices

## 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 enables programmatic catalog management and grants advertisers more control over how their catalogs are ingested and updated.

A catalog holds everything regarding the user's product and product set and is associated with the user's handle. **Currently, one user can only create one catalog.**

The Catalog API supports two ways to ingest products:

1. **Scheduled Feed**: Add a feed URL (CSV, TSV, or XML) that will be periodically fetched. X supports files up to 8GB.
2. **Batch Products API**: View, create, update, and delete product attributes with batch (JSON) requests.

X merchants can create product sets based on filter rules. This allows attaching additional metadata to products and creating special product sets for organic commerce features or Dynamic Product Ads. The Catalog API and X Shopping Manager support two types of product sets:

1. **Manual**: Select up to 50 products and set a name and description.
2. **Filter**: Add up to 30 filters to automatically generate sets (price, Google product category, product type, inventory, sale price, custom fields, etc.).

### Prerequisites

Catalog API endpoints are currently available via **early-access only**. To apply for access, please reach out to your X representative or fill out the appropriate form.

You must accept the terms of service via [X Shopping Manager](https://ads.x.com/shopping_manager).

For product specifications and Shopping Manager details, see the [Product specifications guide](https://business.x.com/en/help/shopping-specs.html).

### Rate Limits

#### Product Catalog

| Endpoint                                                                                                                                | Rate limit           |
| :-------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |
| [GET /product\_catalogs](/x-ads-api/catalog-management/reference#get-product_catalogs)                                                  | 1,000 per 15 minutes |
| [POST /product\_catalogs](/x-ads-api/catalog-management/reference#post-product_catalogs)                                                | 20 per 15 minutes    |
| [PUT /product\_catalogs/:product\_catalog\_id](/x-ads-api/catalog-management/reference#put-product_catalogs%2Fproduct_catalog_id)       | 20 per 15 minutes    |
| [DELETE /product\_catalogs/:product\_catalog\_id](/x-ads-api/catalog-management/reference#delete-product_catalogs%2Fproduct_catalog_id) | 20 per 15 minutes    |

#### Batch Products API

| Endpoint                                                                                                                                                    | Rate limit           |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |
| [GET /product\_catalogs/:product\_catalog\_id/products](/x-ads-api/catalog-management/reference#get-product_catalogs%2Fproduct_catalog_id%2Fproducts)       | 1,000 per 15 minutes |
| [PUT /product\_catalogs/:product\_catalog\_id/products](/x-ads-api/catalog-management/reference#put-product_catalogs%2Fproduct_catalog_id%2Fproducts)       | 600 per 15 minutes   |
| [DELETE /product\_catalogs/:product\_catalog\_id/products](/x-ads-api/catalog-management/reference#delete-product_catalogs%2Fproduct_catalog_id%2Fproducts) | 150 per 15 minutes   |

#### Product Sets

| Endpoint                                                                                                                                                                                                | Rate limit           |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |
| [GET /product\_catalogs/:product\_catalog\_id/product\_sets](/x-ads-api/catalog-management/reference#product-sets)                                                                                      | 2,000 per 15 minutes |
| [POST /product\_catalogs/:product\_catalog\_id/product\_sets](/x-ads-api/catalog-management/reference#post-product_catalogs%2Fproduct_catalog_id%2Fproduct_sets)                                        | 100 per 15 minutes   |
| [PUT /product\_catalogs/:product\_catalog\_id/product\_sets/:product\_set\_id](/x-ads-api/catalog-management/reference#put-product_catalogs%2Fproduct_catalog_id%2Fproduct_sets%2Fproduct_set_id)       | 500 per 15 minutes   |
| [DELETE /product\_catalogs/:product\_catalog\_id/product\_sets/:product\_set\_id](/x-ads-api/catalog-management/reference#delete-product_catalogs%2Fproduct_catalog_id%2Fproduct_sets%2Fproduct_set_id) | 100 per 15 minutes   |

#### Scheduled Feeds

| Endpoint                                                                                                                                                                                                            | Rate limit           |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |
| [GET /product\_catalogs/:product\_catalog\_id/scheduled\_feeds](/x-ads-api/catalog-management/reference#get-product_catalogs%2Fproduct_catalog_id%2Fscheduled_feeds)                                                | 1,000 per 15 minutes |
| [POST /product\_catalogs/:product\_catalog\_id/scheduled\_feeds](/x-ads-api/catalog-management/reference#post-product_catalogs%2Fproduct_catalog_id%2Fscheduled_feeds)                                              | 20 per 15 minutes    |
| [PUT /product\_catalogs/:product\_catalog\_id/scheduled\_feeds/:scheduled\_feed\_id](/x-ads-api/catalog-management/reference#put-product_catalogs%2Fproduct_catalog_id%2Fscheduled_feeds%2Fscheduled_feed_id)       | 20 per 15 minutes    |
| [DELETE /product\_catalogs/:product\_catalog\_id/scheduled\_feeds/:scheduled\_feed\_id](/x-ads-api/catalog-management/reference#delete-product_catalogs%2Fproduct_catalog_id%2Fscheduled_feeds%2Fscheduled_feed_id) | 20 per 15 minutes    |

## Full API Reference

For the complete reference (Product Catalogs, Products, Product Sets, and Scheduled Feeds endpoints), see the **[Catalog Management API Reference](/x-ads-api/catalog-management/reference)** page.


# Catalog Management API Reference
Source: https://docs.x.com/x-ads-api/catalog-management/reference

Complete technical reference for all Catalog Management endpoints in the X Ads API — Product Catalogs, Products, Product Sets, and Scheduled Feeds.

## API Reference

<Note>
  This is the full technical reference. For an overview of Catalog Management concepts, product feeds, and Dynamic Product Ads, see the
  <a href="/x-ads-api/catalog-management">Catalog Management Overview</a>.
</Note>

<Note type="warning">
  These endpoints are currently available via early-access only. To apply for access, please fill out <a href="https://docs.google.com/forms/d/1EbtgnfDjAaSYH_QkWq64eNl6cZM-snVuppjpxoBxWJ8/viewform?edit_requested=true">this form</a> or reach out to your X representative.
</Note>

### Product Catalogs

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET product\_catalogs[](#get-product_catalogs "Permalink to this headline")

Retrieve details for some or all product catalogs associated with the authenticated user (default) or the user specified in the `user_id` parameter.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField type="long">
  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.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
GET https://ads-api.x.com/12/product_catalogs
```

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {}
  },
  "next_cursor": null,
  "data": [
    {
      "id": "1547080201384865792",
      "name": "Catalog Name"
    }
  ]
}
```

#### POST product\_catalogs[](#post-product_catalogs "Permalink to this headline")

Create a product catalog. One user can only create one catalog that holds all products. X merchants need to create a catalog before uploading products.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField type="string">
  Name of your product catalog.
</ParamField>

<ParamField type="long">
  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.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

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

#### PUT product\_catalogs/:product\_catalog\_id[](#put-product_catalogs%2Fproduct_catalog_id "Permalink to this headline")

Update a product catalog.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id`

<ParamField type="string">
  Identifier of your product catalog.
</ParamField>

<ParamField type="string">
  Name of your product catalog.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
PUT https://ads-api.x.com/12/product_catalogs/1547080201384865792?name=My Catalog
```

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "id": "1547080201384865792",
      "name": "My Catalog"
    }
  },
  "data": {
    "id": "1547080201384865792",
    "name": "My Catalog"
  }
}
```

#### DELETE product\_catalogs/:product\_catalog\_id[](#delete-product_catalogs%2Fproduct_catalog_id "Permalink to this headline")

Delete a product catalog. **This is a permanent deletion.**

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id`

<ParamField type="string">
  Identifier of your product catalog.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
DELETE https://ads-api.x.com/12/product_catalogs/1559919496399204352
```

**Example Response[](#example-response "Permalink to this headline")**

```json theme={null}
{
  "request": {
    "params": {
      "id": "1559919496399204352"
    }
  },
  "data": {
    "id": "1559919496399204352",
    "name": "catalog dos"
  }
}
```

### Products

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

X merchants are able to send a synchronous batch request to view, create, edit, and delete products, instead of having to upload a feed file.

There are two types of products: individual products vs product groups. A product group is a group of multiple variants and is created when the user provides an `item_group_id` and has multiple variants for the product. When you call a fetch endpoint for products that includes grouped products, only the product that you submitted first will be returned.

#### GET product\_catalogs/:product\_catalog\_id/products[](#get-product_catalogs%2Fproduct_catalog_id%2Fproducts "Permalink to this headline")

Retrieve details for some or all products associated with the specified Product Catalog.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id/products`

<ParamField type="string">
  This is a X-generated item group identifier.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 100
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

Please refer to the [product specifications guide](https://business.x.com/en/help/shopping-specs.html) for details about responses.

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792",
      "count": 1
    }
  },
  "next_cursor": "1547080787865939970",
  "data": [
    {
      "inventory": 5,
      "custom_label_2": null,
      "item_group_key": null,
      "additional_image_link": null,
      "size": null,
      "mobile_link": null,
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
      "price": "20.00 USD",
      "gtin": null,
      "age_group": "teen",
      "availability": "in stock",
      "product_type": "",
      "color": null,
      "custom_label_3": null,
      "item_group_id": null,
      "brand": "X",
      "product_key": "1547080787865939969",
      "mpn": null,
      "id": "123abc",
      "custom_label_4": null,
      "condition": "new",
      "custom_label_0": null,
      "sale_price": null,
      "custom_label_1": null,
      "link": "https://www.x.com/twtr_blue",
      "sale_price_effective_date": null,
      "image_link": "https://t.co/jeans_1.jpg",
      "title": "My shoes",
      "google_product_category": "Apparel & Accessories > Shoes",
      "gender": "female"
    }
  ]
}
```

#### PUT product\_catalogs/:product\_catalog\_id/products[](#put-product_catalogs%2Fproduct_catalog_id%2Fproducts "Permalink to this headline")

Add new products or update existing ones via a batch request. In a single request, up to 25 products can be supported.

A PUT request needs all of the required fields from the attribute list below. If we do not recognize the `id`, we create a new product. If we recognize the `id` in your catalog, we update the corresponding existing product.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id/products`

**Request Attributes (JSON body)**[](#request-attributes-json-body "Permalink to this headline")

<ParamField type="string">
  Unique ID for the item. Use the SKU if possible. If there are multiple instances of the same ID, all instances will be ignored.
</ParamField>

<ParamField type="string">
  Unique product object identifier generated by X.
</ParamField>

<ParamField type="string">
  The name of the product. Should be the same name as the product from the landing product page given through `link` or `mobile_link` attributes. Max 150 characters.
</ParamField>

<ParamField type="string">
  The description of the product. This field does not support HTML and must be in plain text. Max 5000 characters.
</ParamField>

<ParamField type="enum">
  Current availability of your item.<br /><br />
  Possible values: `in stock`, `available for order`, `preorder`, `out of stock`, `discontinued`
</ParamField>

<ParamField type="enum">
  Condition of the item being sold.<br /><br />
  Possible values: `new`, `used`, `refurbished`
</ParamField>

<ParamField type="string">
  Price of the item. Format as a number followed by the 3-digit ISO currency code (ISO 4217), with a space between cost and currency. Use `.` as the decimal point.
</ParamField>

<ParamField type="string">
  URL of the product page where people can buy the item. Must include `https`.
</ParamField>

<ParamField type="string">
  URL for the primary image of your item. Must be JPG, GIF, WEBP, or PNG. Minimum 500x500px. Max file size 5MB.
</ParamField>

<ParamField type="string">
  The brand name of the item. Required if `gtin` and `mpn` are not available.
</ParamField>

<ParamField type="string">
  Global Trade Item Number (UPC, EAN, JAN, or ISBN). Required if `brand` and `mpn` are not available.
</ParamField>

<ParamField type="string">
  Manufacturer Part Number. Required if `gtin` and `brand` are not available.
</ParamField>

<ParamField type="string">
  URL of a mobile-optimized product page. Must include `https`.
</ParamField>

<ParamField type="string">
  Comma-separated list of up to 10 additional image URLs. Follow the same specs as `image_link`.
</ParamField>

<ParamField type="string">
  Category according to Google's product taxonomy (path or ID).
</ParamField>

<ParamField type="string">
  Your business's custom product taxonomy. Subcategories separated by `>` (with spaces).
</ParamField>

<ParamField type="int">
  Quantity available to sell. Must be ≥ 1 when `availability` is `in stock`.
</ParamField>

<ParamField type="string">
  Discounted price (must be lower than `price`). Same format as `price`.
</ParamField>

<ParamField type="string">
  Time range for the sale period in ISO-8601 format: `YYYY-MM-DDTHH:MM+HH:MM/YYYY-MM-DDTHH:MM+HH:MM`.
</ParamField>

<ParamField type="string">
  Groups product variants together (size, color, age\_group, gender). Required if the product has variants.
</ParamField>

<ParamField type="string">
  X-generated item group identifier.
</ParamField>

<ParamField type="enum">
  Gender for item sizing.<br /><br />
  Possible values: `female`, `male`, `unisex`
</ParamField>

<ParamField type="string">
  Primary color of the product (do not use hex codes).
</ParamField>

<ParamField type="string">
  Size of the item (word, abbreviation, or number).
</ParamField>

<ParamField type="enum">
  Associated age group.<br /><br />
  Possible values: `adult`, `all ages`, `teen`, `kids`, `toddler`, `infant`, `newborn`
</ParamField>

<ParamField type="string">
  Extra custom label.
</ParamField>

<ParamField type="string">
  Extra custom label.
</ParamField>

<ParamField type="string">
  Extra custom label.
</ParamField>

<ParamField type="string">
  Extra custom label.
</ParamField>

<ParamField type="string">
  Extra custom label.
</ParamField>

**Response Parameters[](#response-parameters "Permalink to this headline")**

<ParamField type="array">
  Warnings about your request.
</ParamField>

<ParamField type="array">
  Error messages about your request.
</ParamField>

<ParamField type="string">
  Unique product object identifier generated by X.
</ParamField>

<ParamField type="string">
  Unique ID for the item.
</ParamField>

<ParamField type="enum">
  Status of your request.<br /><br />
  Possible values: `CREATE_SUCCESS`, `UPDATE_SUCCESS`, `ERROR`, `NO_CHANGE`
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
PUT https://ads-api.x.com/12/product_catalogs/1547080201384865792/products
```

**JSON Body**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "products": [
    {
      "id": "test-12345",
      "title": "Test Product 1",
      "description": "The product which was added from the upsert endpoint",
      "availability": "in stock",
      "condition": "new",
      "link": "https://www.x.com/twtr_blue",
      "image_link": "https://www.kurzweilai.net/images/Naam-Limits-of-Earth-Part1-001-earth-600x600.jpg",
      "brand": "x",
      "gtin": "1432563728",
      "mpn": "3268793T",
      "mobile_link": "https://www.x.com/twtr_blue",
      "google_product_category": "Apparel & Accessories > Clothing > Dresses",
      "product_type": "Apparel & Accessories > Clothing > Dresses",
      "inventory": 2,
      "price": "60.00 USD",
      "gender": "female",
      "color": "blue",
      "size": "medium",
      "sale_price": "50.00 USD",
      "sale_price_effective_date": "2022-10-04T17:20:31.000Z/2022-10-10T04:00:00.000Z",
      "age_group": "adult",
      "custom_label_0": "custom value"
    }
  ]
}
```

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792"
    }
  },
  "data": {
    "products_response": [
      {
        "warnings": [],
        "errors": [],
        "product_key": "1576769414321651714",
        "id": "test-123456",
        "status": "CREATE_SUCCESS"
      }
    ]
  }
}
```

#### DELETE product\_catalogs/:product\_catalog\_id/products[](#delete-product_catalogs%2Fproduct_catalog_id%2Fproducts "Permalink to this headline")

Delete existing products. **This is a permanent deletion.**

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id/products`

**Request Parameters (JSON body)**[](#request-parameters-json-body-1 "Permalink to this headline")

<ParamField type="array">
  Array of unique product object identifiers generated by X.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
DELETE https://ads-api.x.com/12/product_catalogs/1569782857975087104/products
```

**JSON Body**

```json theme={null}
{
  "product_keys": [
    "1576769414321651714",
    "1577536549830344705"
  ]
}
```

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "product_keys": [
        "1576769414321651714",
        "1577536549830344705"
      ]
    }
  },
  "data": {
    "delete_products": [
      {
        "product_key": "1576769414321651714",
        "failed_product_key": null,
        "message": null
      },
      {
        "product_key": "1577536549830344705",
        "failed_product_key": null,
        "message": null
      }
    ]
  }
}
```

### Product Sets

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

Product Sets are collections of products which represent a subset of your catalog (e.g. "Fall Sale Products"). You can use product sets to run Dynamic Product Ads (DPA) featuring the specific products included in that collection, rather than all products in your catalog.

#### GET product\_catalogs/:product\_catalog\_id/product\_sets/:product\_set\_id[](#get-product_catalogs%2Fproduct_catalog_id%2Fproduct_sets%2Fproduct_set_id "Permalink to this headline")

Retrieve details for a specific Product Set associated with the specified Product Catalog.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id/product_sets/:product_set_id`

<ParamField type="string">
  Unique ID for the product set.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
GET https://ads-api.x.com/12/product_catalogs/1547080201384865792/product_sets/1560456755976343552
```

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792",
      "id": "1560456755976343552"
    }
  },
  "data": {
    "name": "Test Product Set API",
    "description": "Price and Custom Filter",
    "product_ids": [
      "123abc",
      "myshoes2"
    ],
    "processing_status": "DONE",
    "id": "1560456755976343552",
    "filters": [
      {
        "attribute": "price",
        "operator": "LESS_THAN",
        "value": "120.00 USD"
      },
      {
        "attribute": "custom_field_5",
        "operator": "MATCH",
        "value": "test"
      }
    ],
    "type": "FILTERED"
  }
}
```

#### POST product\_catalogs/:product\_catalog\_id/product\_sets[](#post-product_catalogs%2Fproduct_catalog_id%2Fproduct_sets "Permalink to this headline")

Create a new product set.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id/product_sets`

**Request Parameters (JSON body)**[](#request-parameters-json-body-2 "Permalink to this headline")

<ParamField type="string">
  Name of the product set.
</ParamField>

<ParamField type="string">
  Description of the product set.
</ParamField>

<ParamField type="enum">
  Type of product set.<br /><br />
  Possible values: `MANUAL`, `FILTERED`
</ParamField>

<ParamField type="array">
  Required when `type` is `FILTERED`. Array of filter objects with `attribute`, `operator`, and `value`.<br /><br />
  Supported attributes: `price`, `product_type`, `google_product_category`, `sale_price`, `inventory`, `custom_label_0` through `custom_label_4`.<br /><br />
  Supported operators: `GREATER_THAN`, `EQUAL_TO`, `LESS_THAN`, `MATCH`, `NOT_CONTAINS`, `CONTAINS`.
</ParamField>

<ParamField type="array">
  Required when `type` is `MANUAL`. Array of X-generated product keys.
</ParamField>

**Response Parameters[](#response-parameters "Permalink to this headline")**

<ParamField type="enum">
  Status of product set creation when using `FILTERED` type.<br /><br />
  Possible values: `DONE`, `PROCESSING`, `FAILED`
</ParamField>

**Example Request (MANUAL type)**[](#example-request-manual-type "Permalink to this headline")

```json theme={null}
POST https://ads-api.x.com/12/product_catalogs/1569782857975087104/product_sets
```

**JSON Body**

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

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "product_catalog_id": "1569782857975087104",
      "name": "manual API product set",
      "type": "MANUAL",
      "product_keys": [
        "1569784751351013380"
      ]
    }
  },
  "data": {
    "name": "manual API product set",
    "description": null,
    "product_ids": [
      "sdkljsdijf"
    ],
    "processing_status": "DONE",
    "id": "1573806483589849088",
    "filters": [],
    "type": "MANUAL"
  }
}
```

**Example Request (FILTERED type)**[](#example-request-filtered-type "Permalink to this headline")

```json theme={null}
POST https://ads-api.x.com/12/product_catalogs/1569782857975087104/product_sets
```

**JSON Body**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "name": "filtered API product set",
  "description": "price above 100 USD",
  "type": "FILTERED",
  "filters": [
    {
      "attribute": "price",
      "operator": "GREATER_THAN",
      "value": "100.00 USD"
    }
  ]
}
```

**Example Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "product_catalog_id": "1569782857975087104",
      "name": "filtered API product set",
      "description": "price above 100 USD",
      "type": "FILTERED",
      "filters": [
        {
          "attribute": "price",
          "operator": "GREATER_THAN",
          "value": "100.00 USD"
        }
      ]
    }
  },
  "data": {
    "name": "filtered API product set",
    "description": "price above 100 USD",
    "product_ids": [
      "nike-sb-dunk-high-pro-medium-grey-pink",
      "sdkljsdijf"
    ],
    "processing_status": "DONE",
    "id": "1573831671954096128",
    "filters": [
      {
        "attribute": "price",
        "operator": "GREATER_THAN",
        "value": "100.00 USD"
      }
    ],
    "type": "FILTERED"
  }
}
```

#### PUT product\_catalogs/:product\_catalog\_id/product\_sets/:product\_set\_id[](#put-product_catalogs%2Fproduct_catalog_id%2Fproduct_sets%2Fproduct_set_id "Permalink to this headline")

Update an existing product set. **Note**: Updating `FILTERED` product sets is not supported. The example below shows a `MANUAL` product set update.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id/product_sets/:product_set_id`

**Request Parameters (JSON body)**[](#request-parameters-json-body-3 "Permalink to this headline")

<ParamField type="string">
  Unique ID for the product set.
</ParamField>

<ParamField type="string">
  Name of the product set.
</ParamField>

<ParamField type="string">
  Description of the product set.
</ParamField>

<ParamField type="array">
  Array of X-generated product keys (for MANUAL sets).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
PUT https://ads-api.x.com/12/product_catalogs/1549442554172694528/product_sets/1564499160082001920
```

**JSON Body**

```json theme={null}
{
  "name": "Update name product catalogs",
  "product_keys": ["1576768397127606272", "1547080787865939969"]
}
```

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "product_catalog_id": "1576873894266273792",
      "id": "1564499160082001920",
      "product_keys": [
        "1576768397127606272",
        "1547080787865939969"
      ],
      "name": "Update name product catalogs"
    }
  },
  "data": {
    "name": "Update name product catalogs",
    "description": "Manual product Sets description",
    "product_ids": [
      "test-12345",
      "123abc"
    ],
    "processing_status": "DONE",
    "id": "1564499160082001920",
    "filters": [],
    "type": "MANUAL"
  }
}
```

#### DELETE product\_catalogs/:product\_catalog\_id/product\_sets/:product\_set\_id[](#delete-product_catalogs%2Fproduct_catalog_id%2Fproduct_sets%2Fproduct_set_id "Permalink to this headline")

Delete an existing product set. **This is a permanent deletion.**

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id/product_sets/:product_set_id`

<ParamField type="string">
  Unique ID for the product set.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
DELETE https://ads-api.x.com/12/product_catalogs/1547080201384865792/product_sets/1559806000097787904
```

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792",
      "id": "1559806000097787904"
    }
  },
  "data": {
    "name": "Filtered Product",
    "description": "Filtered product Set",
    "product_ids": [],
    "processing_status": "DONE",
    "id": "1559806000097787904",
    "filters": [
      {
        "attribute": "price",
        "operator": "GREATER_THAN",
        "value": "100.00 USD"
      }
    ],
    "type": "FILTERED"
  }
}
```

### Scheduled Feeds

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

Scheduled Feeds configure the file location and frequency with which X ingests product data into a user's catalog. Only one product feed is supported per user.

Importing a scheduled feed is an **additive** action — removing products from the feed does **not** delete them from the catalog.

#### GET product\_catalogs/:product\_catalog\_id/scheduled\_feeds[](#get-product_catalogs%2Fproduct_catalog_id%2Fscheduled_feeds "Permalink to this headline")

Retrieve details for scheduled feeds associated with the specified Product Catalog.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id/scheduled_feeds`

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
GET https://ads-api.x.com/12/product_catalogs/1547080201384865792/scheduled_feeds
```

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "start_time": "01:30",
      "product_catalog_id": "1547080201384865792",
      "feed_url": "https://test212/file.csv",
      "feed_format": "CSV",
      "id": "1564821386714947589",
      "created_at": "2022-08-31T03:44:26.000Z",
      "frequency": "DAILY",
      "repeat": null,
      "updated_at": "2022-09-27T08:47:23.000Z",
      "time_zone": "America/New_York"
    }
  ]
}
```

#### POST product\_catalogs/:product\_catalog\_id/scheduled\_feeds[](#post-product_catalogs%2Fproduct_catalog_id%2Fscheduled_feeds "Permalink to this headline")

Create a scheduled product feed.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id/scheduled_feeds`

<ParamField type="string">
  Host feed URL for your product file. Can be up to 8GB.
</ParamField>

<ParamField type="enum">
  Format of the product feed file.<br /><br />
  Possible values: `CSV`, `TSV`, `XML`
</ParamField>

<ParamField type="enum">
  How often X should ingest the feed.<br /><br />
  Possible values: `HOURLY`, `DAILY`, `WEEKLY`
</ParamField>

<ParamField type="string">
  Required for `WEEKLY` or `HOURLY` frequency.<br /><br />

  * `WEEKLY`: `MONDAY`–`SUNDAY`<br />
  * `HOURLY`: `1`, `2`, `3`, `4`, `6`, `8`, `12`<br />
  * `DAILY`: Do not include this parameter.
</ParamField>

<ParamField type="string">
  Time to import the feed file (HH:MM format).
</ParamField>

<ParamField type="string">
  IANA time zone for `start_time`.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
POST https://ads-api.x.com/12/product_catalogs/1547080201384865792/scheduled_feeds?feed_url=https://test212/file.csv&feed_format=CSV&frequency=WEEKLY&time_zone=America/New_York&repeat=SATURDAY&start_time=01:30
```

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "start_time": "01:30",
      "product_catalog_id": "1547080201384865792",
      "feed_url": "https://test212/file.csv",
      "feed_format": "CSV",
      "frequency": "WEEKLY",
      "repeat": "SATURDAY",
      "time_zone": "America/New_York"
    }
  },
  "data": {
    "start_time": "01:30",
    "product_catalog_id": "1547080201384865792",
    "feed_url": "https://test212/file.csv",
    "feed_format": "CSV",
    "id": "1576851765428822016",
    "created_at": "2022-10-03T08:28:52.000Z",
    "frequency": "WEEKLY",
    "repeat": "SATURDAY",
    "updated_at": "2022-10-03T08:28:52.000Z",
    "time_zone": "America/New_York"
  }
}
```

#### PUT product\_catalogs/:product\_catalog\_id/scheduled\_feeds/:scheduled\_feed\_id[](#put-product_catalogs%2Fproduct_catalog_id%2Fscheduled_feeds%2Fscheduled_feed_id "Permalink to this headline")

Update an existing scheduled product feed.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id/scheduled_feeds/:scheduled_feed_id`

<ParamField type="string">
  Unique ID for the scheduled feed.
</ParamField>

<ParamField type="string">
  Host feed URL for your product file (up to 8GB).
</ParamField>

<ParamField type="enum">
  Format of the product feed file.<br /><br />
  Possible values: `CSV`, `TSV`, `XML`
</ParamField>

<ParamField type="enum">
  Ingestion frequency.<br /><br />
  Possible values: `HOURLY`, `DAILY`, `WEEKLY`
</ParamField>

<ParamField type="string">
  Repeat value (see POST for valid values per frequency).
</ParamField>

<ParamField type="string">
  Time to import the feed (HH:MM).
</ParamField>

<ParamField type="string">
  IANA time zone for `start_time`.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
PUT https://ads-api.x.com/12/product_catalogs/1547080201384865792/scheduled_feeds/1577629831247720448?start_time=07:30
```

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792",
      "start_time": "07:30",
      "id": "1577629831247720448"
    }
  },
  "data": {
    "start_time": "07:30",
    "product_catalog_id": "1547080201384865792",
    "feed_url": "https://test212/file.csv",
    "feed_format": "CSV",
    "id": "1577629831247720448",
    "created_at": "2022-10-05T12:00:37.000Z",
    "frequency": "WEEKLY",
    "repeat": "SATURDAY",
    "updated_at": "2022-10-05T12:03:07.000Z",
    "time_zone": "America/New_York"
  }
}
```

#### DELETE product\_catalogs/:product\_catalog\_id/scheduled\_feeds/:scheduled\_feed\_id[](#delete-product_catalogs%2Fproduct_catalog_id%2Fscheduled_feeds%2Fscheduled_feed_id "Permalink to this headline")

Delete an existing scheduled product feed. **This is a permanent deletion.**

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/product_catalogs/:product_catalog_id/scheduled_feeds/:scheduled_feed_id`

<ParamField type="string">
  Unique ID for the scheduled feed.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
DELETE https://ads-api.x.com/12/product_catalogs/1547080201384865792/scheduled_feeds/1576854236993708032
```

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792",
      "id": "1576854236993708032"
    }
  },
  "data": {
    "start_time": "07:30",
    "product_catalog_id": "1547080201384865792",
    "feed_url": "https://test212/file.csv",
    "feed_format": "CSV",
    "id": "1576854236993708032",
    "created_at": "2022-10-03T08:38:41.000Z",
    "frequency": "DAILY",
    "repeat": null,
    "updated_at": "2022-10-03T08:50:10.000Z",
    "time_zone": "America/New_York"
  }
}
```


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

Overview of creative assets on X Ads, including promoted Tweets, cards, images, GIFs, and videos that can be uploaded and attached to ad campaigns.

**Manage all types of promotable content (Tweets, media, cards, polls, etc.) for your X advertising campaigns.**

## Quick links

* [Full API Reference](/x-ads-api/creatives/reference) — Complete reference for all creative endpoints and objects
* [Guides](#guides) — Media Library, Scheduled Tweets, Identifying Cards/Media, Carousels, etc.

## Overview

Creatives are any entity that can be promoted in a campaign. Posts can include text, images, GIFs, videos, or cards. Cards can include images or videos.

Image, GIF, or video creatives are uploaded using either the [POST media/upload](/x-api/media/upload-media#post-media-upload) — a simple upload endpoint that only supports images — or the POST media/upload (chunked) endpoints. These can be added to

cards:

* POST accounts/:account\_id/cards
  Tweets:
* POST accounts/:account\_id/tweets - To add cards to Tweets, use the card\_uri parameter.
  Scheduled Tweets:
* POST accounts/:account\_id/scheduled\_tweets

For additional details on cards, please see the Cards page. The Promoted Video page provides details on associating videos with cards or Tweets.

### Cards

The Ads API supports several card types that can be used in Tweets, which can then be promoted in campaigns. **Note**: once Tweeted, card details are publicly visible. This may include information about the user who owns the card.

#### Image

The following image specifications apply to assets used in [Cards](/x-ads-api/creatives/reference#cards-2). Images must be 3MB or less and have a width of at least 800px. In addition, we support the following width:height aspect ratios.

* Website: 1:1 and 1.91:1
* Image App Download: 1:1 and 1.91:1
* Poll: 1.91:1
* Image Conversation: 1.91:1
* Image Direct Message: 1.91:1

We support the following image formats: .bmp, .jpeg, and .png.

#### Video

The following video specifications apply to assets used in [Cards](/x-ads-api/creatives/reference#cards-2). We support the following width:height aspect ratios.

* Video Website: 16:9 and 1:1
* Video App Download: 16:9 and 1:1
* Poll: 16:9
* Video Conversation: 16:9
* Video Direct Message: 16:9

### Promoted Video

This document provides a brief overview of the process for uploading and promoting video through the Ads API.

The Ads API supports Promoted Video in [Tweets](/x-ads-api/creatives/reference#tweets-2) and in the following cards:

* [Video Website](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [Video App Download](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [Video Conversation](/x-ads-api/creatives/reference#video-conversation-cards)

First, upload the video using the [POST media/upload (chunked)](/x-api/media/initialize-media-upload) endpoint. Using the `media_id`, associate the video with an ads account using the POST accounts/:account\_id/videos endpoint. The video's `id`, sometimes referred to as the `media_key`, will be used in subsequent requests. This is a string that begins with an int, is followed by an underscore, and ends with a long value. As an example, see: `13_875943225764098048`.

#### Promoted Video in Tweets

To create a Tweet, use the [POST accounts/:account\_id/tweet](/x-ads-api/creatives/reference#get-accounts-account-id-tweets) endpoint along with the video's `id`. In this step, you can also provide a video title, description, and call-to-action (CTA). These values are user-facing.

#### Promoted Video in Cards

Video App Download and Video Conversation cards support the ability to add a poster images. Upload an image to use in these cards using the [POST media/upload](/x-api/media/upload-media) endpoint.

Create the card using one of the following endpoints:

* [POST accounts/:account\_id/cards/video\_website](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [POST accounts/:account\_id/cards/video\_app\_download](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [POST accounts/:account\_id/cards/video\_conversation](https://devcommunity.x.com/t/ads-api-version-11/168814)

using the video's `id` and, optionally, the image's `media_id` (for the poster image).

Finally, create the Tweet using the POST accounts/:account\_id/tweet endpoint. Cards are attached to Tweets using the `card_uri` parameter.

#### General Information

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/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.
* Uploaded video should be either mp4 or mov.
* Uploaded video generally processes quickly, but processing times can vary depending on video length and file size.
* Uploaded poster images should be in png or jpg format. There are no aspect ratio or size requirements, but the poster image will be adjusted to fit the video player.

## Guides

### Scheduled Tweets

#### Introduction

Scheduled Tweets allow an advertiser or user to create a Tweet that can be scheduled to go live at a later date. In addition to being able create and manage these Tweets, the API allows the ability to associate these Tweets with a line item, to be promoted once the Tweet goes live. This allows advertisers to stage create native Tweets and plan their campaign creatives in advance of any key initiatives. For example, staging a Tweet creative to live immediately upon a new product announcement.

The full set of functionality provided by the Scheduled Tweets API endpoints are listed below:

* Create, modify and view newly scheduled Tweets
* Associate a Scheduled Tweet with a line item
* Query and manage existing scheduled Tweets
* Once a Scheduled Tweet goes live, retrieve the live Tweet `id`

#### API Endpoints

The entire set of endpoints related to the above functionality is listed below:

#### Scheduled Tweet Management

* [GET accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives/reference#get-accounts-account-id-scheduled-tweets) (retrieve a list of all Scheduled Tweets)
* [GET accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives/reference#get-accounts-account-id-scheduled-tweets) (lookup a specific Scheduled Tweet using its `id`)
* [POST accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives/reference#post-accounts-account-id-scheduled-tweets) (create a new Scheduled Tweet)
* [PUT accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives/reference#example-request-39) (modify an existing Scheduled Tweet)
* [DELETE accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives/reference#example-request-40) (delete a Scheduled Tweet using its `id`)
* [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/x-ads-api/creatives/reference#scheduled-tweets-2) (preview an existing Scheduled Tweet)

#### Scheduled Promoted Tweets

* [GET accounts/:account\_id/scheduled\_promoted\_tweets](/x-ads-api/campaign-management/reference#get-accounts-account-id-scheduled-promoted-tweets) (retrieve 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

* [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/x-ads-api/creatives/reference#scheduled-tweets-2) (view an existing Scheduled Tweet)

Due to the nature of Scheduled Tweets being separate entities from “live” Tweets, there are two different sets of validations run on any creates or edits to these Tweets. The first set of validation rules are run during the Scheduled Tweet creation step, specifically:

#### Scheduled Tweet Create:

* Validate that the authenticated user has access to create organic Tweets for a given @handle Promoted-Only Tweet create privileges requires authenticated user to be an account user with [Tweet composer permissions](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/authenticated-user-access#get-accounts-account-id-authenticated-user-access)
* Validate that there are no more than 30 Tweets that are scheduled to be created within a 15 minute window of the scheduled\_at time. A SCHEDULED\_TWEET\_LIMIT\_EXCEEDED error message indicates that too many Scheduled Tweets have been scheduled within the same future, 15 minute time frame.  Advertisers will need to remove an existing Scheduled Tweet or move the scheduled\_at time earlier or later.

#### Scheduled Tweet goes "live":

* These validation rules are run at the scheduled\_at time and are identical to those applied on regular Tweet creation in the API. For example, a Scheduled Tweet will not go live and the scheduled\_status will be set to FAILED if the Scheduled Tweet contains both an image and a gif

#### Workflow

**Create a new Scheduled Tweet**

A new Scheduled Tweet can be created using the [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets) endpoint. This endpoint has the following required parameters, `scheduled_at` time along with the Tweet `text` if no media entities are included in the Tweet. In addition, this endpoint provides a few additional options that allow you to create a scheduled Tweet on behalf of another @handle via the `as_user_id` param along with the ability to add a card (`card_uri`) and any media (`media_ids`). Note, a Tweet can only contain entities of the same type, i.e., either Video, Gif or Image. The `nullcast` param controls whether the Tweet is a “Promoted-Only” Tweet or not. All newly created Scheduled Tweets are "Promoted-Only" (`nullcast=true`) by default. If `nullcast=false` then an Organic Scheduled Tweet is created

Once a Scheduled Tweet is successfully created, the response will contain an `id` field, which refers to the unique identifier of the Scheduled Tweet itself. In addition to this field, another field called `tweet_id` is also returned. This field is `null` initially, however once the Tweet goes live this field is populated with the ID of the “live” Tweet.

```
twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_tweets" -d 'scheduled_at=2017-12-24T23:59:00Z&text=Happy Holidays!'
```

This will create the following Scheduled Tweet:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "text": "Happy Holidays!",
      "scheduled_at": "2017-12-24T23:59:00Z"
    }
  },
  "data": {
    "completed_at": null,
    "id_str": "917507899668099072",
    "text": "Happy Holidays!",
    "user_id": "3271358660",
    "scheduled_status": "SCHEDULED",
    "id": 917507899668099100,
    "nullcast": true,
    "created_at": "2017-10-09T21:51:44Z",
    "scheduled_at": "2017-12-24T23:59:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T21:51:44Z",
    "tweet_id": null,
    "media_keys": []
  }
}
```

Once this Scheduled Tweet goes live, the `tweet_id` field will be populated with the "live" Tweet's ID.

**View a Scheduled Tweet**

The [GET accounts/:account\_id/tweet\_previews](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweet-previews#get-accounts-account-id-tweet-previews) endpoint can then be used with the Scheduled Tweet `id` from the previous step to generate a preview of the Tweet. The API response will contain an iframe URL that is ready to be used to render a preview for the Scheduled Tweet. The relevant CSS and images will be served directly via X.

```
twurl -H ads-api.x.com -X GET "/6/accounts/18ce54bgxky/tweet_previews?tweet_type=SCHEDULED&tweet_ids=917507899668099072
```

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "tweet_type": "SCHEDULED",
      "tweet_ids": [
        "917507899668099072"
      ],
      "account_id": "18ce54bgxky"
    }
  },
  "data": [
    {
      "tweet_id": "1126633863155871744",
      "preview": "<\iframe class='tweet-preview' src='https://ton.smf1.x.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAK1WTW%2FjNhD9Kyyv9dqSZdmOgALJbhJsCyxaIDkUWBUEJY0lNhSpklRSN%2FV%2F71CyZbm297S%2BWJxPzpt5I71T9wbgaELeaW6AOygYxyN9rlryhW9JcEPmUbKIkuiG%2FBjgj8yD8IZOqChoEobz5TKK1ssojOP1KlwtFl7BrDMY4oIW%2FTatlMzB3z7JZ940W%2FJZS1Hwrf0Btc60Kve3oMmGSwsTWgjbSL7tXJjhqgSafA0mYfzHhIJywgmwNHmnFbeV4yU%2Bf0WN3daZlvtDa8Gw2htrdRCZXrlDU92aHIPStA2CKOekMrD5KaWVc02SztIZps%2Bh0rIAg27TXNcpJQYk2ii90VLqt7R3ht%2B4cQoMeVClUIAPd03Th01nvDfx0ClmoJFYk0aouGst82gqROaKskf03KCr7LLvXnXN02K3QTHFaziovYdH0seL5qswitfLZTBq6FGIRfSe9Lm1FTfkY%2BX%2FFcpPAlNRC7eufdFSY1%2BxASh84oo8YitzYXM9IZ%2FuaNcQ1HjMbQc61l0VXDmYlsJVbTYVGq0KwPCi2cf5tQFFnjR2zyDU6YycwX%2Fr3oRzvfKpwTaSZ8NfQUoU%2FUsetanxAV79VElhHbm1oIrSiILcvvgquqSN0Q7y8Uz2TQdjWa5bhZP8IUShEeh8IvIxkVB7SY%2FyKctaIL%2B0kgQrMp8n0SKJ10eWxZ4t%2FBXHUzg4idu6nOnNxsIQ1Yka2D9aDc0sQTNQPJP%2B2sgqvPUrGLERozL68ToNLRELvBj4VuZaOSOy1mmsdAi2dxaWOeyhlRzVl6TYozMnhHIjJLCM5y%2BlwaweHOn96afg%2FuHhnl60ETUvgR1HpJsQntkptrcuO0bOOhuLg1NBPfyH6Swrpw2W9O24rBu8kwH8DuEdns9Kv1hLc5rsxBaTLcN1HIdhHIVRuFov5wtMXH748vO2%2BP0jUzjFXE7%2FbMa3%2BFZl3z1ZxhWyjv2fwlfy9NaY6LhO0lm4WC3WcRSvlqO4UqiXYT7C%2B7vwcT7SWlFAxg3LtMHNfH2ODnZ4kIPVPRo9jnN1r5eDNup%2BIy2y5GxuDrQqYMNb6dje9or44HOyQYTnWs%2FXXoD7%2Ba8WrGO4hwZuK%2B2Qt%2F32tAPhB%2B4xt238qjVQtpIbuuvIP6wbjfAIhStncO3eZ0f9keMHmYHuo%2BCwFoJ%2BDfktdEF0JPfebbxgct30b%2BdhY%2B51u%2FGm2U2IR7rW%2FbJU%2FdcBfpEchHjwoO52%2FwENmVvErwgAAA%3D%3D'>"
    }
  ]
}
```

A sample view of the newly created Scheduled Tweet is shown above

**Associate a Scheduled Tweet with a line item**

While Scheduled Tweets can be used to create Organic Tweets, we also allow partners to create a “Promoted-Only” (`nullcast=true`) Tweet either one of which can be associated with a line item. In order to facilitate this, we provide a [POST accounts/:account\_id/scheduled\_promoted\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/scheduled-promoted-tweets#post-accounts-account-id-scheduled-promoted-tweets) endpoint as well. This endpoint only allows a single Promoted Scheduled Tweet to be associated with a line item in a single API call. In order to associate multiple Scheduled Tweets to the same line item, multiple API calls are necessary.

Please note that it is not possible to modify an existing Scheduled Promoted Tweet.

```
twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_promoted_tweets" -d 'line_item_id=a44qc&scheduled_tweet_id=917507899668099072'
```

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "line_item_id": "a44qc",
    "id": "26576",
    "created_at": "2017-10-09T22:24:16Z",
    "updated_at": "2017-10-09T22:24:16Z",
    "scheduled_tweet_id": "917507899668099072",
    "tweet_id": null,
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "a44qc",
      "scheduled_tweet_id": 917507899668099100,
      "account_id": "aaaaa"
    }
  }
}
```

This endpoint only creates an association between a given Scheduled Tweet and a line item. Once the campaign/line item flight dates are current, the line item with automatically start serving the corresponding “live” Tweet. While we do validate during this step that the Scheduled Tweet is in the `SCHEDULED` state, and that the given Scheduled Tweet is valid for the given objective, no other validations are run. Any remaining validation rules that apply to the line item and Scheduled Tweet are run when the Tweet goes “live”

In order to ensure that there are no issues with campaign serving it is recommend that the Scheduled Tweet be `scheduled_at` a time prior to the campaign/line item flight dates.

For example, let's say the Scheduled Tweet is set to go live after the campaign start date (and that there is only a single Tweet associated with a single line item), then the campaign will be `ACTIVE`, however given that the Scheduled Tweet is not live yet, there will be no creatives available for serving.

**Scheduled Tweet Management**

The remaining sets of endpoints allow API consumers to manage all their Scheduled Tweets and Scheduled Promoted Tweets. These APIs can be used to either return a list of all Scheduled Tweets optionally filtered by a given state as well as lookup a given Scheduled Tweet by its `id`.

#### What happens when a Scheduled Tweet goes live?

Once a given Scheduled Tweet is about to go live, or in other words at the `scheduled_at` time, the following updates are made:

* The “live” Tweet is created however this may have a latency of upto 1 second
* The `tweet_id` is added to the following entities:
* Scheduled Tweet
* Promoted Scheduled Tweet
* A new Promoted Tweet entity is created

#### Best Practices

The following best practices are recommended when creating or promoting Scheduled Tweets:

* Ensure that the Tweet is valid when creating the Scheduled Tweet (for example, a Tweet can only have either an Image, Video or Gif and not any combination of the three)
* Ensure that the campaign flight dates (i.e., the `start_time` and `end_time`) align with the `scheduled_at` time for the Scheduled Tweet
* Scheduled Tweets should not be scheduled for more than one year in the future (365 days)
* Tweet preview is currently not supported for Scheduled Tweets (this is ability to preview Scheduled Tweets prior to creation)

### Media Library

#### Introduction

The Media Library endpoints provide the ability to manage images, GIFs, and videos for X Ads accounts. Media assets in the library can be used in Tweets and to create cards. They can also be reused in multiple [creatives](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/overview), eliminating the need to upload the same asset multiple times.

#### API Endpoints

* [POST media/upload](/x-api/media/upload-media) or [POST media/upload (chunked)](/x-api/media/initialize-media-upload) (upload media)
* [POST accounts/:account\_id/media\_library](https://developer.x.com/x-ads-api/creatives/reference#get-accounts-account-id-media-library#post-accounts-account-id-media-library) (add media to the Media Library)

#### Adding to the Library

Adding media to the library is a two-step process. First, upload the asset using either the [POST media/upload](/x-api/media/upload-media) endpoint or the [POST media/upload (chunked)](/x-api/media/initialize-media-upload) set of endpoints. (See the [Chunked media upload](/x-api/media/quickstart/media-upload-chunked) guide for details on our multi-part upload process.)

```
twurl -X POST -H upload.x.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file latte.jpeg --file-field "media"
```

```json theme={null}
{
   "media_id":966947208837742592,
   "media_id_string":"966947208837742592",
   "size":74194,
   "expires_after_secs":86400,
   "image":{
      "image_type":"image/jpeg",
      "w":800,
      "h":418
   }
}
```

Next, using the media ID, add the media to the ads account’s library using the [POST accounts/:account\_id/media\_library](https://developer.x.com/x-ads-api/creatives/reference#get-accounts-account-id-media-library#post-accounts-account-id-media-library) endpoint.

```
twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library?file_name=latte.jpeg&media_category=TWEET_IMAGE&media_key=966947208837742592&name=Latte"
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
   "request":{
      "params":{
         "name":"Latte",
         "file_name":"latte.jpeg",
         "media_category":"TWEET_IMAGE",
         "account_id":"18ce54d4x5t",
         "media_key":966947208837742592
      }
   },
   "data":{
      "tweeted":false,
      "name":"Latte",
      "file_name":"latte.jpeg",
      "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "media_category":"TWEET_IMAGE",
      "media_key":"3_966947208837742592",
      "created_at":"2018-02-23T08:05:54Z",
      "media_status":"TRANSCODE_COMPLETED",
      "media_key":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}
```

**Note:** Tweeting images, GIFs, or videos directly after the upload also adds media to the library.

#### Request Parameters

All Media Library POST requests require a media identifier. This value is returned during the upload step. When using the media\_id, as in the example above, a media\_category must also be specified. There are four possible category values: AMPLIFY\_VIDEO, TWEET\_GIF, TWEET\_IMAGE, and TWEET\_VIDEO.

Optionally, name and file\_name values can be set for objects in the Media Library. These attributes help users distinguish between media variants in the library.

For videos, it’s also possible to set a title and a description. They values are intended to be passed as the video\_title and video\_description request parameters with the [POST accounts/:account\_id/tweet](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. In the Tweet, this text appears under the video.

#### Attributes

The Media Library, formally introduces the concept of the media\_key. This is the unique identifier for objects in the library. Media keys are string values in the following format: 13\_875943225764098048. These are fully supported in all of our card endpoints.

In addition, the Media Library response includes the media\_id, represented as a string. This is included for resources that do not currently accept a media key: [Tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet)\*, [Tweet preview](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#get-accounts-account-id-tweet-preview)\*, and [Scheduled Tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets). We are working toward supporting media keys everywhere.

The aspect\_ratio attribute is returned for GIFs and videos. This can be used to filter media for use in cards that only accept particular aspect ratios.

\*These endpoints support the video\_id parameter, which is a media key.

#### Usage

In this section, the following image will be used in a Tweet and to create a website card.

```
twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library/3_966947208837742592"
```

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
   "request":{
      "params":{
         "account_id":"18ce54d4x5t",
         "media_key":"3_966947208837742592"
      }
   },
   "data":{
      "tweeted":false,
      "name":"Latte",
      "file_name":"latte.jpeg",
      "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "media_category":"TWEET_IMAGE",
      "media_key":"3_966947208837742592",
      "created_at":"2018-02-23T08:05:54Z",
      "media_status":"TRANSCODE_COMPLETED",
      "media_key":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}
```

**Tweet**

We can create the Tweet by referencing the images using media\_keys.

```
twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet?text=coffee&media_keys=966947208837742592&as_user_id=756201191646691328&trim_user=true"
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
   "data":{
      "created_at":"Fri Feb 23 08:20:05 +0000 2018",
      "id":966950781302665218,
      "id_str":"966950781302665218",
      "text":"coffee https://t.co/T772Hx5GNT",
      "truncated":false,
      "entities":{
         "hashtags":[

         ],
         "symbols":[

         ],
         "user_mentions":[

         ],
         "urls":[

         ],
         "media":[
            {
               "id":966947208837742592,
               "id_str":"966947208837742592",
               "indices":[
                  7,
                  30
               ],
               "media_url":"http://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "media_url_https":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "url":"https://t.co/T772Hx5GNT",
               "display_url":"pic.x.com/T772Hx5GNT",
               "expanded_url":"https://x.com/apimctestface/status/966950781302665218/photo/1",
               "type":"photo",
               "sizes":{
                  "thumb":{
                     "w":150,
                     "h":150,
                     "resize":"crop"
                  },
                  "large":{
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "medium":{
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "small":{
                     "w":680,
                     "h":355,
                     "resize":"fit"
                  }
               }
            }
         ]
      },
      "source":"Ads API Internal Test App",
      "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":756201191646691328,
         "id_str":"756201191646691328"
      },
      "geo":null,
      "coordinates":null,
      "place":null,
      "contributors":[
         2417045708
      ],
      "retweet_count":0,
      "favorite_count":0,
      "favorited":false,
      "retweeted":false,
      "possibly_sensitive":false,
      "scopes":{
         "followers":false
      },
      "lang":"en"
   },
   "request":{
      "params":{
         "as_user_id":756201191646691328,
         "text":"coffee",
         "account_id":"18ce54d4x5t",
         "media_keys":[
            966947208837742592
         ],
         "trim_user":true
      }
   }
}
```

**Website Card**

All of our cards endpoints support media keys. We will create the [website card](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/website#post-accounts-account-id-cards-website) by referencing the image’s media\_key.

```
twurl -X POST -H ads-api.x.com "/11/accounts/18ce54d4x5t/cards"
```

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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"
      }
    }
  ]
}
```

We then associate this card with a Tweet using its card\_uri.

### Identifying Cards

#### Introduction

Cards are customizable ad formats that use media and that can be associated with a website, an app, or with calls to action to drive certain user engagements, such as starting a Direct Message. They can be appended to Tweets, Scheduled Tweets, or Draft Tweets.

Cards may be referenced in Tweet objects in one of two ways: by the card's card\_uri or by its preview\_url. Example values for each are presented below.

| card\_uri                  | preview\_url                                                                               |
| :------------------------- | :----------------------------------------------------------------------------------------- |
| card://1043282691834048513 | [https://cards.x.com/cards/18ce54d4x5t/68w3s](https://cards.x.com/cards/18ce54d4x5t/68w3s) |

**Note**: As of Ads API version 3, only the card\_uri is generated and returned in the cards response for newly created cards.

**Note**: As of Ads API version 5, the preview\_url in the cards response is no longer returned.

The type of reference in the Tweet object response will depend on the way the Tweet was created. In other words, if the Tweet was created using the card\_uri request parameter, the card URI value will appear in the response. If the preview\_url was included as part of the Tweet text, on the other hand, the preview URL will appear in the response.

#### Identifying Tweets with card\_uri

For Tweets created using the card's URI value, find the reference to the card in the card\_uri response attribute. The example response below uses the [GET accounts/:account\_id/tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#get-accounts-account-id-tweets) endpoint.

```bash title="Example request" expandable lines wrap icon="terminal" theme={null}
$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweets?trim_user=true&tweet_type=PUBLISHED&tweet_ids=1043551275923591168"
{
  "request": {
    "params": {
      "tweet_ids": [
        "1043551275923591168"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "source": "Ads API Internal Test App",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        15
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1043551275923591168",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 1043551275923591168,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Sat Sep 22 17:23:07 +0000 2018",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "card_uri": "card://1043282691834048513",
      "full_text": "Tracking a card",
      "lang": "en",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1043551275923591168"
    }
  ]
}
```

If using the Standard API, use include\_card\_uri=true in the request.

Regardless of which endpoint is used, the card\_uri response attribute will only be rendered if the Tweet was created using a card URI.

For scheduled and draft Tweet objects, the response will always include the card\_uri response attribute.

#### Identifying Tweets with preview\_url

For Tweets created by including the preview URL as part of the Tweet's text, the URL can be found in entities\["urls"]\[i]\["expanded\_url"] (the text field includes a shortened t.co URL), where i is an array index (a Tweet can contain multiple URLs).

For scheduled and draft Tweet objects, the preview URL will always appear in the text field.

#### Fetching cards

To retrieve additional information about a specific card, we provide two endpoints: [GET accounts/:account\_id/cards/all](https://developer.x.com/en/docs/ads/creatives/api-reference/cards-fetch.html#get-accounts-account-id-cards-all) and [GET accounts/:account\_id/cards/all/:card\_id](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/cards-fetch#get-accounts-account-id-cards-all-card-id). The former allows a card to be fetched by card\_uri and the latter by the card's ID. The card's ID is found at the end of the preview\_url. In the example above, the ID is 68w3s.

### Identifying Media

#### Introduction

Media—images, GIFs, and videos—can be added to Tweets and cards. In addition, videos can be used as pre-roll assets and images can be promoted on the [X Audience Platform](https://developer.x.com/en/docs/ads/measurement/overview/twitter-audience-platform). This section describes how to find media references across these entities.

There are two types of media identifiers: IDs and keys. Example values for each are presented below.

| **Media ID**        | **Media key**           |
| :------------------ | :---------------------- |
| 1029825579531807971 | 13\_1029825579531807971 |

The media key is the ID plus a numeric prefix and an underscore.

#### Images

The following table shows the identifier types currently available in each image-related resource's response as well as the corresponding attribute name(s).

| **Resource**    | **Identifier** | **Attribute(s)**                                                |
| :-------------- | :------------- | :-------------------------------------------------------------- |
| Image cards     | None           |                                                                 |
| Tweet           | Both           | `entities["media"]["id_str"]`  `entities["media"]["media_key"]` |
| Scheduled Tweet | Both           | `media_ids` and `media_keys`                                    |
| Draft Tweet     | Both           | `media_ids` and `media_keys`                                    |
| Account Media   | None           |                                                                 |
| Media Library   | Both           | `media_id` and `media_key`                                      |

Image cards and Account Media images do not include a reference any media identifier. Tweets only include media IDs. Scheduled and Draft Tweets include both the media ID and media key. The Media Library returns both, too.

For Tweets, the id and id\_str fields in the object within the entities\["media"] array correspond to the media ID. In cases where a Tweet includes multiple images, the references to each media entity can only found in extended\_entities\["media"].

In addition to references to identifiers, it's often important to have access to the image's URL.

| **Resource**    | **Attribute(s)**                                                                    | **Format** |
| :-------------- | :---------------------------------------------------------------------------------- | :--------- |
| Image cards     | `image`                                                                             | .jpg       |
| Tweet\*         | `entities["media"][0]["media_url"]` or `extended_entities["media"][i]["media_url"]` | .jpg       |
| Scheduled Tweet | None                                                                                |            |
| Draft Tweet     | None                                                                                |            |
| Account Media   | `media_url`                                                                         | .jpg       |
| Media Library   | `media_url`                                                                         | .jpg       |

\* This URL locations depend on whether the Tweet contains a single image or multiple images.

All image cards include an image response attribute that contains the X image URL. (For image app download cards, the name is wide\_app\_image.)

For Tweets, the media URL location depends on both the type of media and the endpoint being used. For Tweets with a single image, the URL can be found in entities\["media"]\[0]\["media\_url"]. This is true for both the Ads API and the Standard API. When Tweets contain multiple images, however, the URLs can only be found extended\_entities\["media"]\[i]\["media\_url"]. This is only available in the Standard API.

#### Videos

The following table shows the identifier types currently available in each video-related resource's response as well as the corresponding attribute name(s).

| **Resource**     | **Identifier** | **Attribute(s)**                                                |
| :--------------- | :------------- | :-------------------------------------------------------------- |
| Video cards      | May be either  | `video_content_id`                                              |
| Video poll cards | None           |                                                                 |
| Tweet            | Both           | `entities["media"]["id_str"]`  `entities["media"]["media_key"]` |
| Scheduled Tweet  | Both           | `media_ids` and `media_keys`                                    |
| Draft Tweet      | Both           | `media_ids` and `media_keys`                                    |
| Account Media    | Media key      | `video_id`                                                      |
| Media Library    | Both           | `media_id` and `media_key`                                      |

While video cards (with the exception of poll cards with video) include a video\_content\_id response attribute, there is inconsistency in the type of value returned. In some cases, it's a media ID; in others, it's a media key.

Information about how to access the video's URL is shown below.

| **Resource**     | **Attribute(s)**                                                    | **Format**   |
| :--------------- | :------------------------------------------------------------------ | :----------- |
| Video cards      | `video_url` and `video_hls_url`                                     | .vmap  .m3u8 |
| Tweet with video | `extended_entities["media"][i]["video_info"]["variants"][j]["url"]` | .mp4         |
| Scheduled Tweet  | None                                                                |              |
| Draft Tweet      | None                                                                |              |
| Account Media    | None                                                                |              |
| Media Library    | `media_url`                                                         | .mp4         |

Video cards include video\_url and video\_hls\_url response attributes with .vmap and .m3u8 URLs, respectively.

#### Media Library

It's sometimes necessary to retrieve additional information about a media asset. One use case, for video cards, is retrieving the mp4 URL instead of the vmap one. This is available in the Media Library. For details on the available information, see our [Media Library Guide](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/guides/media-library). Most assets belonging to the ads account's FULL promotable user can be found in the library. There are some exceptions, though.

**Fetching media**

As stated above, image cards do not contain references to either media IDs or media keys. As a result, it's not possible to fetch their assets through the Media Library. This is also true for [Account Media](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/account-media#account-media) images.

Video cards require that the video asset be part of the Media Library (or the Videos resource before it) prior to creating it. As a result, these assets will always be retrievable in the Media Library. This is also true for Account Media PREROLL assets.

Finally, media in Tweets are always guaranteed to be in the Media Library.

The following table summarizes which assets are retrievable in the Media Library, taking into account whether the resource response includes an identifier to use in the lookup.

| **Resource**                     | **In the Media Library** |
| :------------------------------- | :----------------------- |
| Image cards                      | No                       |
| Video cards                      | Yes\*                    |
| Tweets (any media)\*\*           | Yes                      |
| Scheduled Tweets                 | Yes                      |
| Draft Tweets                     | Yes                      |
| Account media images             | No                       |
| Account media videos (`PREROLL`) | Yes                      |

\* For cards where the `video_content_id` is a media key. When the value is a media ID, the asset still exists in the Media Library, but retrieving it involves appending a numeric prefix and underscore to it.
\*\* Tweets only return media IDs. While the asset is guaranteed to exist in the Media Library, fetching it involves appending a numeric prefix and underscore to it.

**Interactions with Account Media**

There are two cases where media assets added to the library are automatically added to the Account Media resource.

* When an AMPLIFY\_VIDEO asset is added to the Media Library, it is automatically added as an Account Media asset as a PREROLL creative type.
* When images that have specific dimensions (see "Creative Types" in our [enumerations page](https://developer.x.com/content/developer-twitter/en/docs/ads/general/overview/enums)) are added to the Media Library, they are automatically added as Account Media assets. The creative type (e.g., INTERSTITIAL) depends on the image dimensions.

### Tweets

#### Introduction

The X Ads API supports three types of Tweets: published, scheduled, and draft.

#### Nullcasted Tweets

Tweets may either be nullcasted (a.k.a. "Promoted-only") or organic. Nullcasted Tweets, once published, do not appear in the user's public timeline, though they are public. Organic Tweets, on the other hand, are served to the user's followers and do appear in the user's public timeline.

**Creating Tweets**

Each of the three Tweet create endpoints supports a Boolean nullcast parameter that gives the API user the option to create nullcasted or organic Tweets. Nullcasted Tweets can be created by the user or by anyone who has permission to create Tweets on the user's behalf. Organic Tweets can only be created by the [full promotable user](https://developer.x.com/content/developer-twitter/en/docs/tutorials/ads-api-hierarchy-terminology#promotable-users).

**Updating Tweets**

It is possible to update the nullcast property for scheduled and draft Tweets. For scheduled Tweets, edits can be made until the Tweet's scheduled\_at time. Draft Tweets can be edited indefinitely. Once published, though, it's not possible to change a Tweet from nullcasted to organic or vice versa.

#### Promoting Tweets

Only published and scheduled Tweets may be promoted. These can either be nullcasted or organic; there's no restriction. An advertiser may promote their own Tweets or another user's Tweets as long as they've obtained permission to do so. (See: [Promoting another user's Tweets](https://developer.x.com/content/developer-twitter/en/docs/tutorials/promoting-another-users-content) for more information.)

Multiple Tweets can be promoted in a single campaign. Similarly, a single Tweet may be promoted in one or more campaigns.

To promote published Tweets, use the [POST accounts/:account\_id/promoted\_tweets endpoint](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/promoted-tweets#post-accounts-account-id-promoted-tweets). This associates published Tweets with a line item. To promote scheduled Tweets, use the [POST accounts/:account\_id/scheduled\_promoted\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/scheduled-promoted-tweets#post-accounts-account-id-scheduled-promoted-tweets) endpoint.

#### Tweet IDs

Published, scheduled, and draft Tweet IDs are [numeric](https://developer.x.com/content/developer-twitter/en/docs/basics/twitter-ids)—they are 64-bit unsigned integers. For example, the following published Tweet's ID is 1166476031668015104.

When published or scheduled Tweets are promoted, a corresponding promoted Tweet entity is created. These entities have their own IDs, which are alpha-numeric and are represented as base-36-encoded values. For example, promoting the published Tweet above—that is, associating it a line item 6c62d—returns the following API response.

```bash title="Example request" expandable lines wrap icon="terminal" theme={null}
$ twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/promoted_tweets?line_item_id=6c62d&tweet_ids=1166476031668015104"
{
  "request": {
    "params": {
      "tweet_ids": [
        1166476031668015104
      ],
      "line_item_id": "6c62d",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "line_item_id": "6c62d",
      "id": "3qwlq6",
      "entity_status": "ACTIVE",
      "created_at": "2019-09-12T21:39:10Z",
      "updated_at": "2019-09-12T21:39:10Z",
      "approval_status": "ACCEPTED",
      "tweet_id": "1166476031668015104",
      "deleted": false
    }
  ],
  "total_count": 1
}
```

In addition to the Tweet ID and the line item ID, which were passed into the create request, the response includes an id field with a value of 3qw1q6, which is the promoted Tweet ID.

### Carousels

#### Introduction

The X Ads API supports creating and retrieving video carousels and image carousels. The carousel is a card type that can contain between 2 and 6 media assets. The carousel card can direct a user to a website or encourage them to install a mobile app. For more information about carousels, their benefits, best practices, and FAQs, see our [Carousel Ads on X](https://business.x.com/en/advertising/carousels.html) page.

A carousel, like any other card type, can be used in Tweets and those Tweets can then be promoted. The workflow is the same as what you're already used to:

1. Upload media
2. Create the card
3. Create the Tweet
4. Promote the Tweet

The only difference is with how the card is created. While other card create requests accept query parameters, carousel card create requests only accept JSON POST bodies.

#### Endpoints

The Ads API supports creating and retrieving carousels.

To create a carousel—any kind—use the [POST accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#post-accounts-account-id-cards) endpoint. To retrieve carousels, use the [GET accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#get-accounts-account-id-cards) endpoint.

#### JSON POST Body

Carousels are created using two components. The first specifies the media assets that will be used. The second specifies information about either the website or the app.

Specifically, a carousel card is created by using the following components, in order:

* One `SWIPEABLE_MEDIA`component, which accepts an array of media keys
* *One* of the following:
* A `DETAILS` component to specify website information
* A `BUTTON` component to specify app information

The `SWIPEABLE_MEDIA` component must include a `media_keys` array where you can specify between 2 and 6 images or videos. The order in which the media keys are passed in determine the order in which they will be rendered.

```json theme={null}
{
  "type": "SWIPEABLE_MEDIA",
  "media_keys": [
    "13_1089771253848666112",
    "13_1191948012077092867"
  ]
}
```

As a reminder, you can obtain media keys by making a request to the [GET accounts/:account\_id/media\_library](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/media-library#get-accounts-account-id-media-library) endpoint.

The composition of the second component object depends on whether you wish to direct a user to a website or encourage them to install an app. The table below summarizes the two options. (**Note**: all of the listed keys are required.)

|                            | **Website**                                                        | **App**                                           |
| :------------------------- | :----------------------------------------------------------------- | :------------------------------------------------ |
| Specify the component type | `"type": "DETAILS"`                                                | `"type": "BUTTON"`                                |
| Title/Label                | `"title": "X"`                                                     | `"label": { "type": "ENUM", "value": "INSTALL" }` |
| Destination                | `"destination": { "type": "WEBSITE", "url": "https://www.x.com" }` | `"destination": { "type": "APP", ... }`           |

Putting this together, an example website carousel JSON POST body is shown below.

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "name": "website carousel",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "DETAILS",
      "title": "X",
      "destination": {
        "type": "WEBSITE",
        "url": "https://www.x.com"
      }
    }
  ]
}
```

App destination objects within `BUTTON` components require a country code and at least one app identifier. They optionally accept deep links. For a description of these fields, see the [reference documentation](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#app-destination).

Putting this together, an example app carousel JSON POST body is shown below.

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "name": "app carousel",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android",
        "iphone_app_id": "333903271"
      }
    }
  ]
}
```

#### Example

This section demonstrates how to create a video website carousel card and how to use it in a Tweet. As mentioned above, the workflow is the same as what you're already used to: upload media, create the card, create the Tweet. The only difference is how the card is created.

**Media**

To start, either upload new media assets or use existing ones. For details on how to upload new media assets and add them to the Media Library, see our [Media Library Guide](https://developer.x.com/en/docs/twitter-ads-api/creatives/guides/media-library).

Once your media assets are in the Media Library, fetch them using the [GET accounts/:account\_id/media\_library](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/media-library#get-accounts-account-id-media-library) endpoint. Use the `media_type` request parameter to scope the results to a particular media type.

```bash theme={null}
$ twurl -H ads-api.x.com "/10/accounts/18ce54d4x5t/media_library?media_type=VIDEO"
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_type": "VIDEO"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "tweeted": true,
      "duration": 5283,
      "name": "Sunrise",
      "file_name": "sunrise.mp4",
      "description": null,
      "media_url": "https://video.twimg.com/amplify_video/1089771253848666112/vid/1280x720/tyL-pUBP7GgkS9bl.mp4?tag=9",
      "poster_media_key": "3_1089771253848666112",
      "media_key": "13_1089771253848666112",
      "created_at": "2019-01-28T06:24:48Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1089771253848666112/img/WOYvToSRZFXUSDzd.jpg",
      "title": null,
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2019-08-23T19:05:33Z",
      "deleted": false
    },
    {
      "tweeted": true,
      "duration": 15248,
      "name": "snow",
      "file_name": "snow.mp4",
      "description": "Two, three, and to the four",
      "media_url": "https://video.twimg.com/amplify_video/1191948012077092867/vid/1280x720/2cOvadcctqqea6Hx.mp4?tag=13",
      "poster_media_key": "3_1191948012077092867",
      "media_key": "13_1191948012077092867",
      "created_at": "2019-11-06T05:18:46Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1191948012077092867/img/IUbhTRd62SEeIVTf.jpg",
      "title": "One",
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2020-03-27T22:23:18Z",
      "deleted": false
    }
  ]
}
```

**Carousel Creation**

Use the [POST accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#post-accounts-account-id-cards) endpoint to create your carousel. Use the media keys from the previous request. Remember, the order in which the media keys are passed in determine the order in which they are rendered.

```bash theme={null}
$ twurl -A "Content-Type: application/json" -X POST -H ads-api.x.com "/10/accounts/18ce54d4x5t/cards" -d '{"name":"website carousel","components":[{"type": "SWIPEABLE_MEDIA","media_keys":["13_1089771253848666112","13_1191948012077092867"]},{"type": "DETAILS","title": "X","destination":{"type":"WEBSITE", "url":"https://www.x.com"}}]}'
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "website carousel",
    "components": [
      {
        "type": "SWIPEABLE_MEDIA",
        "media_keys": [
          "13_1089771253848666112",
          "13_1191948012077092867"
        ]
      },
      {
        "type": "DETAILS",
        "title": "X",
        "destination": {
          "type": "WEBSITE",
          "url": "https://www.x.com/",
          "tco_url": "https://t.co/dyTMHWKWZb"
        }
      }
    ],
    "id": "ars7m",
    "created_at": "2020-11-11T07:51:47Z",
    "card_uri": "card://1326432421105995776",
    "updated_at": "2020-11-11T07:51:47Z",
    "deleted": false,
    "card_type": "UNIFIED"
  }
}
```

Notice that like with other cards, the carousel card response includes a `card_uri`, which will be used when creating a Tweet.

**Tweet**

Use the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint to create your Tweet. Use the `card_uri` from the previous request. (Response truncated for readability.)

```bash theme={null}
$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet_previews?tweet_type=PUBLISHED&tweet_ids=1326434098324385792"
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "created_at": "Wed Nov 11 07:58:27 +0000 2020",
    "id": 1326434098324385792,
    "id_str": "1326434098324385792",
    "text": "Swipe",
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "Ads API Internal Test App",
    "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": 756201191646691300,
      "id_str": "756201191646691328",
      ...
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": [
      2417045708
    ],
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "possibly_sensitive": false,
    "scopes": {
      "followers": false
    },
    "lang": "en"
  },
  "request": {
    "params": {
      "text": "Swipe",
      "as_user_id": 756201191646691300,
      "card_uri": "card://1326432421105995776",
      "account_id": "18ce54d4x5t"
    }
  }
}
```

**Tweet Previews**

Use the [GET accounts/:account\_id/tweet\_previews](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/tweet-previews#get-accounts-account-id-tweet-previews) endpoint to see your Tweet.

### creative-metadata-tagging

#### Introduction

This guide is for creative partners, agencies and creative developers to tag assets used within X campaigns to better understand individual asset value and performance.

**Note:** Media assets must only be tagged by the partner or developer creating the media asset. If the user of the media asset did not create the media asset, do not implement metadata tagging.

Creative Metadata Tagging provides attribution of images and videos created by Creative Partners wherever the asset is uploaded to X, or whomever the entity that is uploading the asset. To create the connection between the creative asset and the creative partner, the [XMP](https://exiftool.org/TagNames/XMP.html) standard is used.

#### Tagging Creative Assets

The following table shows the identifier types currently available in each image-related resource's response as well as the corresponding attribute name(s). A tagging tool is needed to tag creative assets. [ExifTool](https://exiftool.org/), a platform-independent Perl library plus a [command-line application](https://exiftool.org/exiftool_pod.html) for reading, writing, and editing meta information, is recommended. See all supported [file types](https://exiftool.org/#supported).

Follow the provided [instructions to install ExifTool](https://exiftool.org/install.html). There are also software packages offered by [Homebrew](https://formulae.brew.sh/) to further simplify the installation by providing the [exiftool install command](https://formulae.brew.sh/formula/exiftool) for macOS and Linux. Confirm your tool is properly installed by entering exiftool -ver in the command line to return the tool’s version number. Learn more about ExifTool command parameters in [ExifTool documentation](https://exiftool.org/).

Creative partners can assign metadata tags on new or existing creative assets with their X app\_id to the contributor XMP tag, and date tag. The creative assets will follow the existing size restrictions when [Uploading Media](/x-api/media/upload-media). 

**Note:** X's use of the contributor XMP tag ensures metadata captures values for campaigns on X exclusively.

`exiftool -contributor="<YOUR APP ID>" -creative_file.jpg`

`exiftool -date="<date>" -creative_file.jpg`

The app\_id  can be found in the [Developer Console](https://developer.x.com/en/portal/dashboard) under Projects & Apps. Example: 16489123

The following example adds app\_id as the contributor tag and date as the date tag for an image:

```
app_id:858382169
```

```
date:2022-03-13
```

```
creative_file: eiffel_tower.jpg
```

```
exiftool -contributor=858382169 eiffel_tower.jpg
```

```
   1 image files updated
```

```
exiftool -date=2022-03-13 eiffel_tower.jpg
```

```
  1 image files updated
```

Verify that your image has been properly tagged: 

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

Example:

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

```json theme={null}
[XMP]        XMP Toolkit            : Image::ExifTool 12.30
```

```json theme={null}
[XMP]        Contributor            : 858382169
```

```json theme={null}
[XMP]        Date                   : 2022:03:13
```

#### Questions?

If you would like to confirm that your tagging and attribution is successful, please provide sample assets that have been tagged to [adsapi-program@x.com](mailto:adsapi-program@x.com) for a X representative to review.

***

## Full API Reference

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.


# Creatives API Reference
Source: https://docs.x.com/x-ads-api/creatives/reference

Endpoint reference for the X Ads Creatives API covering account media, cards, scheduled Tweets, media library, and promoted video creative operations.

## API Reference

### Account Media

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/account\_media

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

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/account_media`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired account media by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="enum">
  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.<br /><br />
  Possible values: `BANNER`, `BANNER_TABLET`, `INTERSTITIAL`, `INTERSTITIAL_LANDSCAPE`, `INTERSTITIAL_LANDSCAPE_TABLET`, `INTERSTITIAL_TABLET`, `MEDIUM_RECTANGLE`, `PREROLL`, `VAST_PREROLL`
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media?account_media_ids=3wpx`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the account media you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the account media you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

**Note**: To associate a card with a Tweet, use the `card_uri` parameter with either the [POST accounts/:account\_id/tweet](/x-ads-api/creatives/reference#post-accounts-account-id-tweet), [POST statuses/update](/x-api/posts/create-post), [POST accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives/reference#post-accounts-account-id-scheduled-tweets), or the [POST accounts/:account\_id/draft\_tweets](/x-ads-api/creatives/reference#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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="enum">
  Scope the response to just the desired card types by specifying a comma-separated list of enum values.<br /><br />
  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`
</ParamField>

<ParamField type="string">
  Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card IDs may be provided.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 200
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="boolean">
  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.
</ParamField>

<ParamField type="string">
  An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters.<br /><br />
  **Note**: This performs case-insensitive prefix matching.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/:card_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The id of the cards.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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](/x-ads-api/creatives/reference#carousels) for a detailed usage example.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards`

**Parameters[](#parameters "Permalink to this headline")**

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).

```json theme={null}
{
  "name": "some name",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "value"
    }
  ]
}
```

Additional information on components below.

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The name for the card. Maximum length: 80 characters.
</ParamField>

<ParamField type="array">
  Describes the components to use to create the card. Additional information below. Cannot be specified along with `slides`.<br /><br />
  **Note**: The order of the components is important.
</ParamField>

<ParamField type="array">
  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`.<br /><br />
  **Note**: The order of each slide is important.
</ParamField>

#### 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.)

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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.

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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**

<ParamField type="enum">
  The destination type, which determines its schema.<br /><br />
  Possible values: `WEBSITE`
</ParamField>

\| 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` |

<ParamField type="string">
  The iOS app store identifier.<br /><br />
  **Note**: At least one of following is required: `ios_app_store_identifier` or `googleplay_app_id`.
</ParamField>

<ParamField type="string">
  A deep link into the Android app you're promoting.<br /><br />
  **Note**: Can only be used if an `googleplay_app_id` has been provided.
</ParamField>

<ParamField type="string">
  A deep link into the iOS app you're promoting.<br /><br />
  **Note**: Can only be used if an `ios_app_store_identifier` has been provided.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards`

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/1321554298900107264`

**Parameters[](#parameters "Permalink to this headline")**

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).

```json theme={null}
{
  "name": "some name",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "value"
    }
  ]
}
```

Additional information on components and slides in **POST accounts/:account\_id/cards**.

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The name for the card. Maximum length: 80 characters.
</ParamField>

<ParamField type="array">
  Describes the components to use to update the card. Additional information below. Cannot be specified along with `slides`.<br /><br />
  **Note**: The order of the components is important.
</ParamField>

<ParamField type="array">
  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`.<br /><br />
  **Note**: The order of each slide is important.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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`

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/:card_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The id of the card to be deleted.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

Retrieve multiple cards, by `card_uri`, associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/all`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all?card_uris=card://1044294149527166979,card://1044301099031658496`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/all/:card_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the card you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all/508pf`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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": "/x-ads-api/creatives/reference#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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/draft\_tweets

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

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/draft_tweets`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 200
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  Specify the user to retrieve Draft Tweets for. Defaults to the `FULL` promotable user on the account when not set.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the Draft Tweet you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994788364334325760`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/draft_tweets`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="string">
  The text of your status update. Required if no `media_keys` are specified.
</ParamField>

<ParamField type="string">
  Associate a card with the Tweet using the `card_uri` value from any cards response, if available.
</ParamField>

<ParamField type="string">
  Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video.<br /><br />
  **Note**: The media asset must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).
</ParamField>

<ParamField type="boolean">
  Whether to create a nullcasted (or "Promoted-only") Tweet.
</ParamField>

<ParamField type="string">
  The name for the Draft Tweet. Maximum length: 80 characters.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the Draft Tweet you are operating with in the request.
</ParamField>

<ParamField type="string">
  Associate a card with the Tweet using the `card_uri` value from any cards response, if available.<br /><br />
  **Note**: Unset (remove) by specifying the parameter without a value.
</ParamField>

<ParamField type="string">
  Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video.<br /><br />
  **Note**: The media asset must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).<br /><br />
  **Note**: Unset (remove) by specifying the parameter without a value.
</ParamField>

<ParamField type="boolean">
  Whether to create a nullcasted (or "Promoted-only") Tweet.
</ParamField>

<ParamField type="string">
  The text of your status update.
</ParamField>

<ParamField type="string">
  The name for the Draft Tweet. Maximum length: 80 characters.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994747471329873920?text=just setting up my twttr`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the Draft Tweet you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994787835663155200`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/preview/:draft_tweet_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the Draft Tweet you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/preview/996132315829948416`

**Example Response[](#example-response "Permalink to this headline")**

```json theme={null}
{
  "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

**Note**: To associate a card with a Tweet, use the `card_uri` parameter with either the [POST accounts/:account\_id/tweet](/x-ads-api/creatives/reference#post-accounts-account-id-tweet), [POST statuses/update](/x-api/posts/create-post), or [POST accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives/reference#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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters.<br /><br />
  **Note**: This performs case-insensitive prefix matching.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?card_ids=59woh`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the image conversation card you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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](/x-api/media/quickstart/media-upload-chunked) for useful information on uploading images to our endpoints.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the first CTA is clicked.
</ParamField>

<ParamField type="string">
  The media key for an image to be used in this card.<br /><br />
  **Note**: The image must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).<br /><br />
  **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required.
</ParamField>

<ParamField type="string">
  The name for the card.
</ParamField>

<ParamField type="string">
  The text to be displayed after the CTA is clicked. Maximum length: 23 characters.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #).<br /><br />
  **Note**: Required if `title` is `not` set.
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the second CTA is clicked.<br /><br />
  **Note**: Required if `second_cta` is set.
</ParamField>

<ParamField type="string">
  The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters.<br /><br />
  **Note**: Required if `second_cta` is `not` set.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the third CTA is clicked.<br /><br />
  **Note**: Required if `third_cta` is set.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the fourth CTA is clicked.<br /><br />
  **Note**: Required if `fourth_cta` is set.
</ParamField>

<ParamField type="string">
  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.<br /><br />
  **Note**: The image must be in the account's media library.<br /><br />
  **Note**: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required.
</ParamField>

<ParamField type="string">
  The URL to be displayed with the thank you text.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`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[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={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"
  },
  "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](/x-api/media/quickstart/media-upload-chunked) for useful information on uploading images to our endpoints.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the image conversation card you are operating with in the request.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the first CTA is clicked.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #).<br /><br />
  **Note**: Required if `title` is `not` set.
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the second CTA is clicked.<br /><br />
  **Note**: Required if `second_cta` is set.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the third CTA is clicked.<br /><br />
  **Note**: Required if `third_cta` is set.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the fourth CTA is clicked.<br /><br />
  **Note**: Required if `fourth_cta` is set.
</ParamField>

<ParamField type="string">
  The media key for an image to be used in this card.<br /><br />
  **Note**: The image must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).<br /><br />
  **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required.
</ParamField>

<ParamField type="string">
  The name for the card.
</ParamField>

<ParamField type="string">
  The text to be displayed after the CTA is clicked. Maximum length: 23 characters.
</ParamField>

<ParamField type="string">
  The URL to be displayed with the thank you text.
</ParamField>

<ParamField type="string">
  The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters.<br /><br />
  **Note**: Required if `second_cta` is `not` set.
</ParamField>

<ParamField type="string">
  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.<br /><br />
  **Note**: The image must be in the account's media library.<br /><br />
  **Note**: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh?name=moon card`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the image conversation card you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/4i0qe`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/media\_library

Retrieve details for some or all media library objects associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/media_library`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 50
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="enum">
  Scope the response to just the desired media type.<br /><br />
  Possible values: `GIF`, `IMAGE`, `VIDEO`
</ParamField>

<ParamField type="string">
  An optional query to scope resource by `name`, `title`, `file_name`, and `description` fields.<br /><br />
  **Note**: This performs case-insensitive *term* matching.<br /><br />
  Min, Max length: `1`, `255`
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the media library object you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/13_909110614026444802`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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](/x-ads-api/creatives/reference#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](/x-ads-api/creatives/reference#get-accounts-account-id-account-media) asset.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/media_library`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The `media_key` for the uploaded content. A `media_key` is returned in the POST media/upload response when a `media_category` is specified.
</ParamField>

<ParamField type="string">
  The description that appears under the video when Tweeted. Maximum length: 200 characters.<br /><br />
  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](/x-ads-api/creatives/reference#post-accounts-account-id-tweet) endpoint.<br /><br />
  **Note**: Can only be used with videos.
</ParamField>

<ParamField type="string">
  The file name for the media library object. Maximum length: 255.<br /><br />
  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.
</ParamField>

<ParamField type="string">
  The name for the media library object. Maximum length: 100.<br /><br />
  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.
</ParamField>

<ParamField type="string">
  Specify a poster image for the video using the `media_key` of an uploaded image. If not specified, the first frame will be used.<br /><br />
  **Note**: Can only be used with videos.
</ParamField>

<ParamField type="string">
  The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters.<br /><br />
  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](/x-ads-api/creatives/reference#post-accounts-account-id-tweet) endpoint.<br /><br />
  **Note**: Can only be used with videos.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?media_key=3_931236738554519552`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the media library object you are operating with in the request.
</ParamField>

<ParamField type="string">
  The description that appears under the video when Tweeted. Maximum length: 200 characters.<br /><br />
  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](/x-ads-api/creatives/reference#post-accounts-account-id-tweet) endpoint.<br /><br />
  **Note**: Can only be used with videos.
</ParamField>

<ParamField type="string">
  The file name for the media library object. Maximum length: 255.<br /><br />
  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.
</ParamField>

<ParamField type="string">
  The name for the media library object. Maximum length: 100.<br /><br />
  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.
</ParamField>

<ParamField type="string">
  Specify a poster image for the video using the `media_key` of an uploaded image.<br /><br />
  **Note**: Can only be used with videos.
</ParamField>

<ParamField type="string">
  The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters.<br /><br />
  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](/x-ads-api/creatives/reference#post-accounts-account-id-tweet) endpoint.<br /><br />
  **Note**: Can only be used with videos.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/16_844800354743074820?title=cat GIF&description=in space`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the media library object you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/7_860318603387600896`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/cards/poll

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

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/poll`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired poll cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters.<br /><br />
  **Note**: This performs case-insensitive prefix matching.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?card_ids=57i77`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the poll card you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/poll`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  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.<br /><br />
  **Note**: This starts as soon as the card is created and not when it is added to a Tweet.<br /><br />
  Min: 5, Max: 10080
</ParamField>

<ParamField type="string">
  The first poll choice. Maximum length: 25 characters.
</ParamField>

<ParamField type="string">
  The name for the card.
</ParamField>

<ParamField type="string">
  The second poll choice. Maximum length: 25 characters.
</ParamField>

<ParamField type="string">
  The fourth poll choice. Maximum length: 25 characters.<br /><br />
  **Note**: The first, second, and third choices must be set when using this parameter.
</ParamField>

<ParamField type="string">
  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.<br /><br />
  **Note**: The image or video must be in the account's media library.<br /><br />
  **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required.
</ParamField>

<ParamField type="string">
  The third poll choice. Maximum length: 25 characters.<br /><br />
  **Note**: The first and second choices must be set when using this parameter.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`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[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the poll card you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i9t`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  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.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired preroll CTAs by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_ids=8v53k`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the preroll call to action you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="enum">
  The CTA text for the displayed button within the ad.<br /><br />
  Possible values: `GO_TO`, `SEE_MORE`, `SHOP`, `VISIT_SITE`, `WATCH_NOW`
</ParamField>

<ParamField type="string">
  The URL to redirect the user to when the CTA button is clicked.
</ParamField>

<ParamField type="string">
  A reference to the line item you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`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[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={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
  },
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the preroll CTA you are operating with in the request.
</ParamField>

<ParamField type="enum">
  The CTA text for the displayed button within the ad.<br /><br />
  Possible values: `GO_TO`, `SEE_MORE`, `SHOP`, `VISIT_SITE`, `WATCH_NOW`
</ParamField>

<ParamField type="string">
  The URL to redirect the user to when the CTA button is clicked.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0?call_to_action=WATCH_NOW`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the preroll CTA you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={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-08-30T06:08:21Z",
    "deleted": true
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  }
}
```

### Scheduled Tweets

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/scheduled\_tweets

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

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 200
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="long">
  Specify the user to retrieve Scheduled Tweets for. Defaults to the `FULL` promotable user on the account when not set.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the Scheduled Tweet you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the Tweet should be published (or go live).<br /><br />
  **Note**: Tweets can only be scheduled up to one year in the future.<br /><br />
  **Note**: Tweets should only be scheduled at minute-granularity; seconds will be ignored.
</ParamField>

<ParamField type="long">
  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.
</ParamField>

<ParamField type="string">
  The text of your status update. Required if no `media_keys` are specified.
</ParamField>

<ParamField type="string">
  Associate a card with the Tweet using the `card_uri` value from any cards response, if available.
</ParamField>

<ParamField type="string">
  Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video.<br /><br />
  **Note**: The media asset must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).
</ParamField>

<ParamField type="boolean">
  Whether to create a nullcasted (or "Promoted-only") Tweet.
</ParamField>

<ParamField type="string">
  The name for the Scheduled Tweet. Maximum length: 80 characters.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`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[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the Scheduled Tweet you are operating with in the request.
</ParamField>

<ParamField type="string">
  Associate a card with the Tweet using the `card_uri` value from any cards response, if available.<br /><br />
  **Note**: Unset (remove) by specifying the parameter without a value.
</ParamField>

<ParamField type="string">
  Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video.<br /><br />
  **Note**: The media asset must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).<br /><br />
  **Note**: Unset (remove) by specifying the parameter without a value.
</ParamField>

<ParamField type="boolean">
  Whether to create a nullcasted (or "Promoted-only") Tweet.
</ParamField>

<ParamField type="string">
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the Tweet should be published (or go live).
</ParamField>

<ParamField type="string">
  The text of your status update.
</ParamField>

<ParamField type="string">
  The name for the Scheduled Tweet. Maximum length: 80 characters.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875057751231037440?text=winter solstice`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the Scheduled Tweet you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/tweet_previews`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A comma-separated list of identifiers. Up to 200 IDs may be provided.<br /><br />
  **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.
</ParamField>

<ParamField type="enum">
  The Tweet type for the specified `tweet_ids`.<br /><br />
  Possible values: `DRAFT`, `PUBLISHED`, `SCHEDULED`
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "tweet_ids": [
        "1122911801354510336",
        "1102836745790316550"
      ],
      "tweet_type": "PUBLISHED",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "tweet_id": "1122911801354510336",
      "preview": "<iframe class='tweet-preview' src='https://ton.twimg.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAANVYW2%2FbNhT%2BKwJf59iiZDuSgWLI0suyrUXbZBuGaiAoibbZUKRGUk7TIP99h6Jsy4mdC5CX%2BiUiz%2F0cfueQuUH2ijGLZsENKjSjlpWEwhK9VzI4qXUQpQE%2BnuF4FofBTyH8gijEKRogXqIZxlGUYpyEOJ6MJziM46kjEGM1qNhDBbl5IwSx7JszsuIlU8EVyw23DGhWN7JwPqDZnArDBqjkphb0uhUgmsoFQ7Mv4QDH%2Fw4Qk5Zbzgya3aAlNUtLF%2FD9BSjmusqV6BaNYZpUjlnJ9Zb2xFtgVY0uQCnKmjCMCxosNZu%2FytDS2trMslE2oqU5ojUf2ituLdPDQlUZCjQTwCXVXAmhrjIvzi48T3BSmuBUVbUC214x6PEsLnWSaFYLiEpBqqhtDHHZlJCZA0Sf0fsMbWz7ZTvSIUkD1WaSSFqxNdlJuFw6fceTKdQZp3g6nk5THEdJr7D3iRCU14ROPp4F74sLZuycFi7YHUMIElkVdksVCuoNhQHSOZXBWyhxwU2hBsHpCWoLtfauZKCJ1x3zmbQqcHq4XARUlgHYNSBQa2VZ0T9BvkBMG1KoRsKpO8KwqTmT5c6W4MYd%2Fm7H29xBxMWyCX5rRBDhACezyXQWJVtEtCebruAwwUne0dvYgqj53LCNVssrRr4ruUn8ginCJM1Fz%2B0V03zOexv%2BLOzqFgAI8IxJsF4oaTXPG6sg1LvauCEWUmsEBfK%2BXcjqPSHI5ZwLRnJaXC40WHXZEU4ehe0P7eXhFV0w0lauRZEHUW4cgKpFC59Ry2OykV2yavMXZ6N8MawhpIf1khabnXbzUuotrO%2BFvjeWetfYDi8YA3TE4yTGx%2BNJMgnTJJpko9cXvxefT%2BtzIpWuqBh%2BrftePBTZixvLqZTQGbYxPWjHc3tDdzCfjfAYvqbROMY9%2FYLLy8PnxEDHz6kmudIlePEoHyzEYa52KhykAlrunZ%2FtYGFz2ghLOuZD%2B3ekfDPhDnUeun4D2up%2FDTQjYti2eUhlAcG%2BvZkN9jcoJPa6dh1RukZw2zaBTdtRkB0uofVs5GAIFmxL30J9vadZO8jX3SH07ch1oz1bW4x3Yn3UK2N4DkMCYoGxzFfb6KEv137cbppqRwP%2FC6pLR%2BoafTRJpnEaHuPpDFJZKdLOerKd9f4AOqn2%2FOFwPI5DHKZpGOPpJBmnrqU6cpuouxh0hCNHOALCETdHJas1a%2B8OQy5XVMAQG6CcS8jjgsC68Y539olZKm2ZhN7eKr5BXTXOLz6ffXjnxhZkeC25AxQLAMlG32nJ%2Fjz%2F6zVOXO1cQaDypGy0b6WGwVZpnqA4GjsF7o4DcLjipV0%2BQQjGzVZobZyXT5GMSQroPR5HyRiuZfAVJWFP2ZLxxdI%2BQVHqhFZUcnv9xBSWbMUEHCDdv0k5LeualA5Bzy3HQa1dQOpKdlekR5Xuudb0EiPMs31rj3y%2Fq9KqFnx%2B7bGQje5XAhqvyEbmk%2F7FvEmrt6sPrE5Pvw2ruEl%2Bhuvtq8h5BLde17AedeT1OjXBR%2Bg4cxgG%2FWy%2FdKJBkNHqxXO0qmi9L1NDR%2BiZ9zPUwLzr2z97f%2FLujbtxt9TO%2Bg16ZPjtuEDssqny%2FcUCiWz0T56%2F%2B%2FTr6u%2FPX9Xbhf7jezdvOyxjYBygNayOI1hQ0c2I2zvu%2F7COE0H1j%2Bz%2Btx8wgHY0Pnt49aDbPs14zsglu%2B4mcatvo7xedw2w0P%2BGTsAL1pv18No9qTlqHy3Gv89w7LBJmxLeWTu8cBkom6J9xcF8bopLtonJGd6%2BaG4HAWpvDv5VJv2%2FDIKbzSYsrG7Y7e3%2FCm%2FIC8QQAAA%3D'>"
    },
    {
      "tweet_id": "1102836745790316550",
      "preview": "<iframe class='tweet-preview' src='https://ton.twimg.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAO1YbW%2FbNhD%2BK4K%2Bzo3eZdlAMQQttqZrt6FNEXRVIVASJTOhSIWkHDeB%2F%2FuOomXLb%2BuHdQWGzV8s3T13vCOPz539ZKsHjJU9t57sQmCkcJkheLWvO2y9RcJyI8udzkN%2F7ofWDy58LN%2F1ZvbEJqU99zzXT4J4GkbTmRt4cRS5WpFJJcDFCS3YVR2lmcIrvcgNWmJpLZRq5Tx1UkddFDx16mUU8Lv4UhQAV6JjhQ7LnleISjyxSyJbir70PjKBWI3t%2BSd3En2e2JgpogiW9vzJXiC5UKiG50%2BgkV%2BanNPNSyexyBoN5mwQiUHZ4JIgeHwyGbpumLjh1PcDfxZ6XpSE4wyPtXpnWEkKHcSneOLPBpcZLAEmOtk%2B1zaXF%2BqBNDXk3KSOTkY9ZEtSYp6pRdfkqXPCPdh1qQNWYPFz%2BfHls7v7y6s3dZm%2Fci9u29oeLZb1%2B7pZUv6ja%2B5SO3uOw6kZaEsKHYhSWJhQ9rB41SJWQiUe%2BR2boJY0hcJSVajAqSMVUp2EBI6rLnX6FEGnC%2BpLi3UEC644vEryaOqlz18%2FPMCp6zpebL4F1hgwKQRv7bXZ4a4ZoL5rsPE0GmErojRUNojSDTJODDBIgmMgRULX8cblBjn13UMkQCu4pZ3og16vP6%2F1dincb9e4%2FP8v4%2F9EGfeSf2UZm%2BMirOIaj2SLC03nwMlQcV480RVXdr2AZQ2hlEhdx9MYnC2RIIgp2dd3ThSgwHUSQBKgLTiDCwE1Mdqi1Gna8MQR98pzxfQXZQT61IlDdxXEcC7Rm1fsHl96H8sau%2Fer1xew2I%2FQfJ4HsCmjCP0o%2Fr4Rwo6svAQivLvqXn14mRD%2FD%2BnWuX91NkJv%2Bp1D1GWyghJJnbD56HePt%2FjXG%2FJbVd3cHsR4EBFqW0qKvjxSZ%2FWsaXH94d2bbxhdS1Nn5r17CF7cTMurt6%2Ffh7fJRRN0yRDT5wMyntioLIkOCNHM8NdQ3sDLVAetGQTLQpBWw4wANzkuS5RrAEw7MOE0nGFFHo2on3oM0UveiUK7STvXDQpkLQSunqejXFEp9wjJtgSmgGC84pTyh9SY4muDsS5LaXyBqdH0xJ8J3FKYsHhm6CjTPYTB4HZGafrIMaAftE7bblTnLGGPMGYZQw0e1NpC76X2N41iGEO9mReHcTzzAj8ZtbNjJSRlPNmXv19Zb4vrDd1q4hwvZO%2BRMWgpNxUGqveIWT%2FBuFkQWfCJ9eJyKDUT3f6xXjHFLe2HsNqCJmDBuhIMWsEV8NxomjXngoXMCt4xGIqfeSAUBDr6ngjoT8%2FmG4lZc39gX3TW645avmd5yTyK536yG9hjPXijJdQPgajGfjtVZLyqJN56VaTB2SOU4CCogacx09W4C3uJBanISGBqYd83heEcIsPMNnwiSN4pDqkeeiMyA%2F5hkiJQn5LqHnBoBHtZEYqzHBV3tYBV9e5QbW%2B7%2Fcc%2BiSENqvHhFIP2J4oeA01YLXCz%2FfZSJ68vWlZ%2Fxe%2BJgeUbuFdkSwY7%2FclcDqajPSwsBrcjCJPAg8kiidxZ4kep8%2FL6l%2BLdi%2FZ9xriAVr8Zh45W%2Bfoo9vcXyxFjwAyHJH5mHYM2Cx3ceWD2EJ5iPwy8kX9K2N35OpHQE3IkspyLEqL4Kg5e6HlU%2Fwv1rBZuy1H97H7k4gp1VGUb8Dn5gZUhE6Jvnbm6RgC0et8BGWUS78iDcQU32NCb3N797S0c2izTRLDuSWBLOxx2hzCgnq0dzMQF3ul3V32QCdz%2FzzCwg2voSLPRCdHujm%2FMxreeS0lyaBKQi4Rmu9xlD7zcmiF4S6pD%2Bxxz0Xpi6TNouOFTZv6LsJ62QnjRfXi9%2FhONbe6QHREAAA%3D%3D'>"
    }
  ]
}
```

### Tweets

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/tweets

Retrieve Tweet details for the account's full promotable user (default) or the user specified in the `user_id` parameter. This can be any of the [promotable users](/x-ads-api/campaign-management/reference) under the account.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/tweets`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="enum">
  The Tweet type for the specified `tweet_ids`.<br /><br />
  Possible values: `DRAFT`, `PUBLISHED`, `SCHEDULED`
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="boolean">
  Whether to filter out mentions and replies from the list of available Tweets.
</ParamField>

<ParamField type="string">
  An optional query to scope Tweets by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters.<br /><br />
  **Note**: This performs case-insensitive prefix matching.
</ParamField>

<ParamField type="enum">
  Whether to return nullcasted (a.k.a. "Promoted-only") Tweets, organic Tweets, or both.<br /><br />
  Possible values: `ALL`, `NULLCAST`, `ORGANIC`
</ParamField>

<ParamField type="boolean">
  Whether to exclude the user object in the Tweet response. When enabled, the only part of the user object that will be returned is the Tweet's author's user ID.
</ParamField>

<ParamField type="string">
  A comma-separated list of identifiers. Up to 200 IDs may be provided.<br /><br />
  **Note**: The IDs should correspond to the specified `tweet_type`. For example, if a Scheduled Tweet ID is passed in, then the `tweet_type` **must** be `SCHEDULED` in order for that Tweet to be returned in the response.
</ParamField>

<ParamField type="long">
  Specifies the user to scope Tweets to. Defaults to the `FULL` promotable user on the account when not set.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "tweet_ids": [
        "1166476031668015104"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "name": null,
      "source": "<a href="https://ads-api.x.com" rel="nofollow">Ads API Internal Test App</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        9
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1166476031668015104",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "id": 1166476031668015104,
      "in_reply_to_status_id": null,
      "conversation_settings": "EVERYONE",
      "nullcast": true,
      "created_at": "Tue Aug 27 22:22:12 +0000 2019",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "hello, v6",
      "lang": "es",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1166476031668015104"
    }
  ]
}
```

#### POST accounts/:account\_id/tweet

Create a Tweet for the account's full promotable user (default) or the user specified in the `as_user_id` parameter. Both nullcasted (default) and organic Tweet creation is supported. Nullcasted Tweets do not appear in the public timeline and are not served to followers. Either type can be used in campaigns.

If the authenticated user is not the `FULL` promotable user on this account, determine if they have permission to Tweet on behalf this user by making a request to the [GET accounts/:account\_id/authenticated\_user\_access](/x-ads-api/campaign-management/reference) endpoint. A permission of `TWEET_COMPOSER` indicates that the user may use this endpoint to create nullcasted Tweets on behalf of the `FULL` [promotable user](/x-ads-api/campaign-management/reference#get-accounts-account-id-promotable-users).

When using the [upload.x.com endpoint](/x-api/media/initialize-media-upload) for media, pass in the same `user_id` value for the `additional_owners` parameter as the `as_user_id` value that you pass in to this endpoint.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/tweet`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="long">
  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.
</ParamField>

<ParamField type="string">
  The text of your status update. Required if no `media_keys` are specified.
</ParamField>

<ParamField type="string">
  Associate a card with the Tweet using the `card_uri` value from any cards response, if available.
</ParamField>

<ParamField type="enum">
  Choose who can reply to this Tweet. Anyone mentioned can always reply.<br /><br />
  **Note**: This field will *not* be returned in the POST request response, but will be returned when making a GET request.<br /><br />
  **Note**: This parameter only works in Ads API v8 and above.<br /><br />
  Possible values: `EVERYONE`, `FOLLOWING`, `MENTIONED_USERS`
</ParamField>

<ParamField type="string">
  Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video.
</ParamField>

<ParamField type="string">
  The name for the Tweet. Maximum length: 80 characters.
</ParamField>

<ParamField type="boolean">
  Whether to create a nullcasted (or "Promoted-only") Tweet.<br /><br />
  **Note**: Organic Tweets (`nullcast=false`) can only be created for the authenticated user.
</ParamField>

<ParamField type="boolean">
  Whether to exclude the user object in the Tweet response. When enabled, the only part of the user object that will be returned is the Tweet's author's user ID.
</ParamField>

<ParamField type="string">
  Whether the response should be in compatibility or extended mode. See [this](/x-api/fundamentals/post-annotations) for additional information.<br /><br />
  Possible values: `compat`, `extended`
</ParamField>

<ParamField type="enum">
  The CTA for the video.<br /><br />
  Possible values: `VISIT_SITE`, `WATCH_NOW`
</ParamField>

<ParamField type="string">
  The value for the corresponding CTA on the video.
</ParamField>

<ParamField type="string">
  The description that appears under the video. Maximum length: 200 characters.
</ParamField>

<ParamField type="string">
  The title (headline) that appears under the video. Maximum length: 70 characters.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet?text=hello, world&as_user_id=756201191646691328&trim_user=true`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "created_at": "Sat Jun 24 05:08:30 +0000 2017",
    "id": 878479925472251906,
    "id_str": "878479925472251906",
    "text": "hello, world",
    "name": null,
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "<a href='"https://ads-api.x.com"' rel='"nofollow"'>Ads API Internal Test App</a>",
    "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": 756201191646691328,
      "id_str": "756201191646691328"
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": null,
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "scopes": {
      "followers": false
    },
    "lang": "en"
  },
  "request": {
    "params": {
      "text": "hello, world",
      "trim_user": true,
      "as_user_id": 756201191646691328,
      "account_id": "18ce54d4x5t"
    }
  }
}
```

Update the specified Tweet `name` belonging to the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/tweets/:tweet_id/name`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="long">
  A reference to the Tweet you are operating with in the request.
</ParamField>

<ParamField type="string">
  The name for the Tweet. Maximum length: 80 characters.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets/994747471329873920/name?name=new Tweet name`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "tweet_id": 994747471329873920,
      "name": "new Tweet name",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
      "coordinates": null,
      "retweeted": false,
      "name": "new Tweet name",
      "conversation_settings": "EVERYONE",
      "source": "<a href="https://ads-api.x.com" rel="nofollow">Ads API Internal Test App</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        5
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "994747471329873920",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 994747471329873920,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Wed Jan 01 00:00:00 +0000 2020",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "hello",
      "lang": "en",
      "contributors": null,
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "utc_offset": null,
        "name": "Tushar Bhushan",
        "friends_count": 1065,
        "screen_name": "imit8me",
        "location": "San Francisco, CA",
        "protected": false,
        "url": "https://tushdante.github.io",
        "profile_image_url": "http://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_background_color": "C0DEED",
        "profile_use_background_image": true,
        "is_translator": false,
        "geo_enabled": true,
        "description": "Open Sorcerer / Partner Engineer @twitter / Space Traveller | Former evangelist @sendgrid @keen_io",
        "profile_link_color": "1DA1F2",
        "id_str": "3271358660",
        "listed_count": 31,
        "default_profile_image": false,
        "followers_count": 407,
        "profile_image_url_https": "https://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_sidebar_border_color": "C0DEED",
        "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png",
        "favourites_count": 5993,
        "following": null,
        "default_profile": true,
        "withheld_in_countries": [],
        "id": 3271358660,
        "profile_background_tile": false,
        "contributors_enabled": false,
        "follow_request_sent": null,
        "created_at": "Tue Jul 07 22:34:58 +0000 2015",
        "profile_sidebar_fill_color": "DDEEF6",
        "translator_type": "regular",
        "lang": null,
        "profile_text_color": "333333",
        "notifications": null,
        "verified": false,
        "time_zone": null,
        "profile_banner_url": "https://pbs.twimg.com/profile_banners/3271358660/1474853576",
        "statuses_count": 500,
        "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png",
        "is_translation_enabled": false
      },
      "tweet_id": "994747471329873920"
    }
}
```

### Video Conversation Cards

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

**Note**: To associate a card with a Tweet, use the `card_uri` parameter with either the [POST accounts/:account\_id/tweet](/x-ads-api/creatives/reference#post-accounts-account-id-tweet), [POST statuses/update](/x-api/posts/create-post), or [POST accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives/reference#post-accounts-account-id-scheduled-tweets) endpoints.

#### GET accounts/:account\_id/cards/video\_conversation

Retrieve details for some or all video conversation cards associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  Scope the response to just the desired video conversation cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField type="int">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField type="string">
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField type="string">
  An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters.<br /><br />
  **Note**: This performs case-insensitive prefix matching.
</ParamField>

<ParamField type="string">
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

<ParamField type="boolean">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_ids": [
        "5a86h"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "video conversation card",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "id": "5a86h",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "created_at": "2018-01-30T17:53:04Z",
      "card_uri": "card://958397665015775232",
      "title": "Developers",
      "updated_at": "2018-01-30T17:53:04Z",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "deleted": false,
      "card_type": "VIDEO_CONVERSATION"
    }
  ]
}
```

Retrieve a specific video conversation card associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the video conversation card you are operating with in the request.
</ParamField>

<ParamField type="boolean">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_id": "5a86h",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  }
}
```

#### POST accounts/:account\_id/cards/video\_conversation

Create a new video conversation card associated with the specified account.

See [Uploading Media](/x-api/media/quickstart/media-upload-chunked) for useful information on uploading images to our endpoints.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the first CTA is clicked.
</ParamField>

<ParamField type="string">
  The media key for a video to be used in this card.<br /><br />
  **Note**: The video must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).<br /><br />
  **Note**: An aspect ratio of 16:9 is required.
</ParamField>

<ParamField type="string">
  The name for the card.
</ParamField>

<ParamField type="string">
  The text to be displayed after the CTA is clicked. Maximum length: 23 characters.
</ParamField>

<ParamField type="string">
  The title for the card, which appears below the video and above the CTAs. Maximum length: 23 characters.<br /><br />
  **Note**: Required if `second_cta` is `not` set.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #).<br /><br />
  **Note**: Required if `title` is `not` set.
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the second CTA is clicked.<br /><br />
  **Note**: Required if `second_cta` is set.
</ParamField>

<ParamField type="long">
  The media key for a poster image to be used in this card. If not specified, the first frame will be used.<br /><br />
  **Note**: The video must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the third CTA is clicked.<br /><br />
  **Note**: Required if `third_cta` is set.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the fourth CTA is clicked.<br /><br />
  **Note**: Required if `fourth_cta` is set.
</ParamField>

<ParamField type="string">
  The URL to be displayed with the thank you text.
</ParamField>

<ParamField type="string">
  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.<br /><br />
  **Note**: The image must be in the account's media library.
</ParamField>

<ParamField type="string">
  The identifier of a video from the [GET accounts/:account\_id/media\_library](/x-ads-api/creatives/reference#media-library) endpoint which will be used in the instant unlock scenario.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?first_cta=#APIs&first_cta_tweet=Ads API&name=video conversation card&thank_you_text=Build it&title=Developers&media_key=13_958388276489895936`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "video_poster_height": "9",
      "name": "video conversation card",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "account_id": "18ce54d4x5t",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "title": "Developers",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "video_poster_width": "16",
      "card_type": "VIDEO_CONVERSATION"
    }
  }
}
```

Update the specified video conversation card belonging to the current account.

See [Uploading Media](/x-api/media/quickstart/media-upload-chunked) for useful information on uploading images to our endpoints.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the video conversation card you are operating with in the request.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the first CTA is clicked.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #).<br /><br />
  **Note**: Required if `title` is `not` set.
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the second CTA is clicked.<br /><br />
  **Note**: Required if `second_cta` is set.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the third CTA is clicked.<br /><br />
  **Note**: Required if `third_cta` is set.
</ParamField>

<ParamField type="string">
  The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField type="string">
  The Tweet text to be used when the fourth CTA is clicked.<br /><br />
  **Note**: Required if `fourth_cta` is set.
</ParamField>

<ParamField type="string">
  The media key for a video to be used in this card.<br /><br />
  **Note**: The video must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).<br /><br />
  **Note**: An aspect ratio of 16:9 is required.
</ParamField>

<ParamField type="string">
  The name for the card.
</ParamField>

<ParamField type="long">
  The media key for a poster image to be used in this card. If not specified, the first frame will be used.<br /><br />
  **Note**: The video must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).
</ParamField>

<ParamField type="string">
  The text to be displayed after the CTA is clicked. Maximum length: 23 characters.
</ParamField>

<ParamField type="string">
  The URL to be displayed with the thank you text.
</ParamField>

<ParamField type="string">
  The title for the card, which appears below the video and above the CTAs. Maximum length: 23 characters.<br /><br />
  **Note**: Required if `second_cta` is `not` set.
</ParamField>

<ParamField type="string">
  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.<br /><br />
  **Note**: The image must be in the account's media library.
</ParamField>

<ParamField type="string">
  The identifier of a video from the [GET accounts/:account\_id/media\_library](/x-ads-api/creatives/reference#media-library) endpoint which will be used in the instant unlock scenario.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h?name=developers card`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "name": "developers card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T18:02:15Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "VIDEO_CONVERSATION",
      "card_id": "5a86h",
      "name": "developers card"
    }
  }
}
```

Permanently delete the specified video 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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id`

<ParamField type="string">
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField type="string">
  A reference to the video conversation card you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/4i0ya`

**Example Response[](#example-response "Permalink to this headline")**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "name": "video conversation card",
    "id": "4i0ya",
    "created_at": "2017-07-07T01:36:39Z",
    "updated_at": "2017-08-23T13:29:13Z",
    "deleted": true,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "card_id": "4i0ya",
      "card_type": "video_conversation",
      "account_id": "18ce54d4x5t"
    }
  }
}
```


# Accessing Ads accounts
Source: https://docs.x.com/x-ads-api/fundamentals/accessing-ads-accounts

How to access X Ads accounts using OAuth, including advertiser versus developer access tokens, account permissions, and agency multi-account workflows.

# 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/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

There are two methods you can use to make Ads API requests for an advertiser’s account:

1. Making requests on behalf of an Advertiser (**recommended)**
2. Making requests using your account that has been granted access to an Advertiser's account, e.g. an [Agency](https://business.x.com/en/blog/agencies-manage-multiple-Twitter-Ads-accounts.html) supporting multiple accounts.

This document is a brief overview of the differences between these options and should be used in conjunction with our other resources, such as the [multi-user login FAQ](https://business.x.com/en/help/troubleshooting/multi-user-login-faq.html). 

As described in [Authorizing a request](/resources/fundamentals/authentication#authorizing-a-request#authorizing-a-request), all requests to the Ads API require Authorization headers using [OAuth 1.0a](/resources/fundamentals/authentication) with an access token obtained via [3-legged](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow)[OAuth](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) flow. Your application will need to implement a web-based OAuth flow to [obtain access tokens](/resources/fundamentals/authentication#oauth-1-0a-2). Ads API developers should never request that our X advertisers share their login credentials.

By default, each [X developer application](/resources/fundamentals/developer-apps) contains a static **access token** that can be used to make Ads API requests for the account that owns the application. These credentials are ideal for single-account use cases without requiring a 3-legged or [PIN-based OAuth](/resources/fundamentals/authentication#pin-based-authorization) flow. If you aren't accessing another X Ads Account, use these [single-user](/resources/fundamentals/authentication#oauth-1-0a-2) credentials instead of the following steps.

## Levels of access

### App-level permissions

Each user will have a level of access as requested upon [application to the Ads API](/x-ads-api/getting-started/step-by-step-guide):

* **Conversion Only**: User has access to [Mobile](/x-ads-api/measurement/mobile-conversions) and [Web Conversion](/x-ads-api/measurement/web-conversions) endpoints with [read & write](/resources/fundamentals/developer-apps) access.
* **Standard Access**: User has access to [Analytics](/x-ads-api/analytics), [Campaign Management](https://developer.x.com/en/docs/twitter-ads-api/campaign-management/overview), [Creatives](https://developer.x.com/en/docs/twitter-ads-api/creatives/overview), [Custom Audiences](https://developer.x.com/en/docs/twitter-ads-api/audiences/overview), and [Conversion](/x-ads-api/measurement/web-conversions) endpoints with [read & write](/resources/fundamentals/developer-apps) access.

**Note:** Ads API developers who requested access prior to July 2023 may have different levels of access and permissions, and may be limited to five OAuth tokens. See our guide on [increasing access](/x-ads-api/getting-started/increasing-access) to access to additional endpoints or lift token limits for existing applications.

### 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/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.                                                                                                                                              

## Methods of obtaining access tokens

### 1. Obtain an advertiser's (User) access token

There are two methods of obtaining an advertiser’s **access token**. The most common method is via a [3-legged OAuth flow](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) directly from within your web UI. Applications that do not have a publicly accessible UI exposed to advertisers can implement an [PIN-based](/resources/fundamentals/authentication#pin-based-authorization) Oauth process. After the user completes the 3-legged flow, your application will have credentials to make request for their Ads account via the API.

Obtaining user credentials via OAuth flow is the method we **highly recommend** for the majority of Ads API developers to gain access to an advertiser account. It allows you to call the API on behalf of a user and take actions as that user. These tokens do not expire but can be revoked by the user at any time.

### 2. Obtain your (Developer) access token

This option requires the advertiser to [grant your @username](https://business.x.com/en/help/troubleshooting/multi-user-login-faq.html) (or @usernames) access to their X Ads account via the X UI at business.x.com. **Access tokens** obtained through the 3-legged OAuth flow for your account will be able to access the advertiser's X Ads account.

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/reference#accounts) endpoint.

## Differences between these methods

|                                                                    |                               |                                                                       |
| :----------------------------------------------------------------- | :---------------------------- | :-------------------------------------------------------------------- |
|                                                                    | Advertiser (User) OAuth Token | (Developer) OAuth Token  <br /> (@username added to separate account) |
| Access Ads Account                                                 | ✔                             | ✔                                                                     |
| Create Posts on Behalf of User                                     | ✔                             | ✔\*                                                                   |
| Manage Campaigns                                                   | ✔                             | ✔                                                                     |
| Access Analytics                                                   | ✔                             | ✔                                                                     |
| Create Cards on Behalf of User                                     | ✔                             | ✔                                                                     |
| Developer ability to Access  <br />via X Ads UI                    |                               | ✔                                                                     |
| [Rate Limits](/x-api/enterprise-gnip-2.0/fundamentals/rate-limits) | Distinct per Advertiser       | Distinct per Advertiser Account                                       |

<Note>
  **Note:** See **[Obtain your (Developer) access token](/x-ads-api/fundamentals/accessing-ads-accounts#2-obtain-your-developer-access-token)** section above for details.
</Note>

## Sample use case

### Advertiser's access token via OAuth 3-legged web flow

The standard flow is web-based and uses the [3-legged authorization](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) OAuth flow. The screen shots outlined here are part of a sample that you can view the source of at [https://github.com/xdevplatform/twauth-web](https://github.com/xdevplatform/twauth-web).

At some point in your application, you will want to redirect to X in order to authorize your application

<Frame>
  <img alt="image0" />
</Frame>

When you redirect to X with the request token, the user will be prompted to authorize your application

<Frame>
  <img alt="image1" />
</Frame>

Upon authorizing your application, the user will be redirected to the callback URL provided when you generated the request token. You will use this to obtain the permanent access token for this user and store it locally!

<Frame>
  <img alt="image" />
</Frame>


# Currency
Source: https://docs.x.com/x-ads-api/fundamentals/currency

The type of a currency is identified using ISO-4217. This is a three-letter string like USD or EUR. The value of a currency is represented in micros.

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.

The Ads API recognizes official currencies of all countries where the X SMB Ads product is available. For a complete list of these countries, please click [here](https://business.x.com/en/help/overview/about-eligibility-for-twitter-ads.html).

Most currencies have a “precision” of two (like USD: \$1.23).

* `AED`, `VEF`, `PKR`, `IDR`, `HKD`, `QAR`, `PHP`, `NZD`, `INR`, `EUR`, `ARS`, `THB`, `MXN`, `EGP`, `DZD`, `SAR`, `LBP`, `COP`, `TRY`, `SGD`, `MAD`, `AUD`, `USD`, `MYR`, `CAD`, `BRL`, `GBP`.

The following currencies don’t use a decimal:

* `VND`, `KRW`, `CLP`, `JPY`

And these use three decimal places:

* `KWD`, `IQD`, `BHD`, `TND`

The usage of currency is accomplished through [funding instruments](/x-ads-api/introduction).


# Error codes and responses
Source: https://docs.x.com/x-ads-api/fundamentals/error-codes-and-responses

Reference for X Ads API response structure and error handling, listing HTTP status codes, error code constants, and common debugging troubleshooting tips.

## 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/reference#campaigns)

```json theme={null}
{
  /* the data of your response... */,
  "request": {
    "params": {
      "account_id": "abcdefg",
      "with_deleted": "true"
    }
  }
}
```

The `data` field in JSON responses will contain the specific objects associated with the leveraged resource. The format of the `data` node will be a JSON array when the response may contain one or more results. It will be returned as JSON hash when only one result is possible in response. In some rare cases, you may see a response that would typically include a collection with a hashmap instead. In this case, assume the single hashmap is an object of the same type as specified in the `type` field.

## Error response structure

Error responses are served with a non-200-series HTTP code. Usually a JSON response will be attached, but some errors will respond with different kinds of body. In these circumstances where a response structure cannot be parsed, consider the HTTP code’s core meaning to take precedence. For instance, you may occasionally see an HTTP 404 along with an HTML response. In this case, it’s safe to assume that the content cannot be found (HTTP 404 means “Not Found”).

Typical error responses follow a similar structure to successful responses. The nature of the error will be communicated in an `errors` node of the response. The `errors/code` node will indicate a CAPS\_CASE constant error code you can programmatically consume to make resolution decisions from. The `errors/message` node will indicate a (usually) human-readable description of the error in English. Additional fields may be attached to indicate finer-grained detail about the error.

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "errors": [
    {
      "parameter": "start_time",
      "details": "invalid date",
      "code": "INVALID_PARAMETER",
      "value": "",
      "message": "Expected time, got \"\" for start_time"
    }
  ],
  "request": {
    "params": {
      "account_id": "hkk5"
    }
  }
}
```

In the above example, a request to an analytics endpoint was made with an invalid value for the `start_time` parameter. The `errors/code` for requests with invalid parameters is `INVALID_PARAMETER`.

| HTTP Code | Error Code                                                  |
| :-------- | :---------------------------------------------------------- |
| 403       | `ACCOUNT_LOCKED_OUT`                                        |
| 404       | `ACCOUNT_MEDIA_NOT_FOUND`                                   |
| 403       | `ACCOUNT_NOT_FOUND`                                         |
| 403       | `ACTION_NOT_ALLOWED`                                        |
| 404       | `APP_EVENT_PROVIDER_CONFIGURATION_NOT_FOUND`                |
| 404       | `APP_EVENT_TAG_NOT_FOUND`                                   |
| 404       | `BEHAVIOR_OR_BEHAVIOR_EXPANDED_NOT_FOUND`                   |
| 404       | `CAMPAIGN_NOT_FOUND`                                        |
| 408       | `CANCELLED_REQUEST`                                         |
| 404       | `CARD_NOT_FOUND`                                            |
| 403       | `CURRENT_USER_SUSPENDED`                                    |
| 400       | `DUPLICATE_TWEET`                                           |
| 400       | `EXCLUSIVE_PARAMETERS`                                      |
| 400       | `FEATURE_NOT_AVAILABLE`                                     |
| 403       | `FUNDING_INSTRUMENT_ACCESS_NOT_ALLOWED`                     |
| 403       | `FUNDING_INSTRUMENT_EXCEEDS_AVAILABLE_CREDIT_LIMIT`         |
| 404       | `FUNDING_INSTRUMENT_NOT_FOUND`                              |
| 403       | `GENERIC_TWEET_ERROR`                                       |
| 400       | `ILLEGAL_CHARACTERS`                                        |
| 400       | `INCLUSIVE_PARAMETERS`                                      |
| 500       | `INTERNAL_ERROR`                                            |
| 404       | `INVALID_APP_ID`                                            |
| 404       | `INVALID_APP_STORE`                                         |
| 400       | `INVALID_DENOMINATION`                                      |
| 400       | `INVALID_FUNDING_INSTRUMENT`                                |
| 404       | `INVALID_IAB_CATEGORY`                                      |
| 404       | `INVALID_ID_ILLEGAL_CHARACTERS`                             |
| 400       | `INVALID_IMAGE`                                             |
| 400       | `INVALID_MEDIA`                                             |
| 400       | `INVALID_MEDIA_ID`                                          |
| 400       | `INVALID_PARAMETER`                                         |
| 400       | `INVALID_PLACEMENT_TYPE`                                    |
| 400       | `INVALID_TAILORED_AUDIENCE_TYPE`                            |
| 400       | `INVALID_TARGETING_TYPE`                                    |
| 400       | `INVALID_TIME_WINDOW`                                       |
| 400       | `INVALID_TV_SHOW_LOCATIONS`                                 |
| 400       | `INVALID_TWEET`                                             |
| 400       | `INVALID_USER`                                              |
| 400       | `INVALID_USER_ID`                                           |
| 423       | `LOCK_ACQUISITION_TIMEOUT`                                  |
| 404       | `LINE_ITEM_APP_NOT_FOUND`                                   |
| 404       | `LINE_ITEM_NOT_FOUND`                                       |
| 404       | `MACT_APP_NOT_FOUND`                                        |
| 403       | `MALWARE_STATUS`                                            |
| 404       | `MEDIA_CREATIVE_NOT_FOUND`                                  |
| 404       | `MEDIA_NOT_FOUND`                                           |
| 405       | `METHOD_NOT_ALLOWED`                                        |
| 400       | `MISSING_PARAMETER`                                         |
| 404       | `NO_PROVIDER_AVAILABLE_FOR_THIS_CLIENT_APPLICATION`         |
| 404       | `NOT_FOUND`                                                 |
| 404       | `PROMOTABLE_USER_NOT_FOUND`                                 |
| 404       | `PROMOTED_ACCOUNT_NOT_FOUND`                                |
| 404       | `PROMOTED_TWEET_NOT_FOUND`                                  |
| 403       | `READONLY_CLIENT_APPLICATION`                               |
| 400       | `REQUEST_TOO_COMPLEX`                                       |
| 404       | `ROUTE_NOT_FOUND`                                           |
| 503       | `SERVICE_UNAVAILABLE`                                       |
| 503       | `OVER_CAPACITY`                                             |
| 400       | `SPEND_EXCEEDS_BUDGET`                                      |
| 404       | `TAILORED_AUDIENCE_CHANGE_FILE_NOT_FOUND`                   |
| 404       | `TAILORED_AUDIENCE_NOT_FOUND`                               |
| 404       | `TAILORED_AUDIENCE_OR_TAILORED_AUDIENCE_EXPANDED_NOT_FOUND` |
| 404       | `TARGETING_CRITERION_NOT_FOUND`                             |
| 400       | `TOO_MANY_CAMPAIGNS`                                        |
| 400       | `TOO_MANY_LINE_ITEMS`                                       |
| 429       | `TOO_MANY_REQUESTS`                                         |
| 400       | `TV_SHOW_OUTSIDE_MARKET`                                    |
| 400       | `TWEET_CANNOT_BE_BLANK`                                     |
| 403       | `TWEET_IS_SPAM`                                             |
| 404       | `TWEET_NOT_FOUND`                                           |
| 429       | `TWEET_RATE_LIMIT_EXCEEDED`                                 |
| 401       | `UNAUTHORIZED_ACCESS`                                       |
| 403       | `UNAUTHORIZED_CLIENT_APPLICATION`                           |
| 400       | `UNKNOWN_CARD_TYPE`                                         |
| 400       | `UNKNOWN_CRITERIA_TYPE`                                     |
| 403       | `USER_NOT_FOUND`                                            |
| 404       | `WEB_EVENT_TAG_NOT_FOUND`                                   |


# Ads API hierarchy and terminology
Source: https://docs.x.com/x-ads-api/fundamentals/hierarchy-and-terminology

Glossary of X Ads API hierarchy and terminology covering accounts, campaigns, line items, creatives, cards, funding instruments, and audience concepts.

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.

<img alt="X Ads API hierarchy" />

## Ad Group (line items)

Ad groups, known as [line items](https://developer.x.com/content/developer-twitter/en/docs/tutorials/ads-api-hierarchy-terminology#line-items) on the Ads API, exist under campaigns and are used for targeting and bidding against a set of X users. Advertisers promote posts or media (e.g., videos that are promoted as In-stream ads) by associating them with a line item. Also see Ad Group.

## Account Media

A collection of creatives that have been uploaded to an ads account as [account media](/x-ads-api/creatives/reference#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

At the top of the X Ads hierarchy are ads accounts. An ads account can be managed by multiple X users. @Furni, our demo furniture store, would be an example of a user who manages an ads account. We identify ads accounts by an account\_id, which is a [base36](https://en.wikipedia.org/wiki/Base36) alpha-numeric string.

Under each account, we store a number of entity types that can be reused across campaigns, such as tailored audiences that can be used for targeting, account media, which are videos or images, and cards, which are expanded creatives that you can add to a post.

## Amplify Video

When uploading a video asset, the uploading entity can define a category for the video (e.g., Tweet Video, Tweet Gif, Tweet Image and Amplify Video). The amplify video category is required when trying to upload a video that is to be served as an in-stream advertisement. These videos require special processing to ensure that they’re servable and hence the media category of Amplify Video is required.

## Analytics

Analytics metrics help partners and advertisers understand the performance of the content they promote on X. This includes information such as impressions, clicks, video views, and spend. In addition, partners and advertisers are able to get detailed metrics for various segments of the audiences they reach.

The Ads API supports two ways of retrieving detailed campaign performance metrics: synchronously and asynchronously.

With [synchronous analytics](/x-ads-api/analytics#synchronous-analytics) requests, the requested metrics are returned in the response. The synchronous endpoint supports short time ranges and is ideal for querying real-time campaign performance.

With the [asynchronous analytics](/x-ads-api/analytics#asynchronous-analytics) endpoints, the requested metrics are available in a downloadable results file after the associated "job" has finished processing. The asynchronous endpoints support requesting metrics over a much longer time range, allows returning segmented data, and are intended for fetching much more data -- ideal for generating reporting or historical backfills.

## Campaigns

Each campaign that the advertiser runs must be created under an existing funding instrument. A campaign lets you define things like the name, schedule, and budget of an ad campaign. In sticking with the example of Furni, we might create a campaign called “Furni home decor”.

It’s worth noting that an ads account is limited to a max of 200 active Campaigns; this limit can be elevated by the advertiser’s account manager. A Campaign is deemed active until its end time is reached or its budget is exhausted. A paused campaign is still considered an active campaign for the purposes of campaign limits.

## Cards

Cards offer a way to visually extend a Tweet to include an image, video or UI elements. The Ads API supports several card types that can be used in Tweets, which can then be promoted in campaigns.

## Creatives

Advertisers can promote Tweets in campaigns that include creatives, such as images, GIFs, and video. These creatives can be associated with X cards that allow attaching rich photos, videos and media experiences to Tweets. Creatives can also be directly attached to Tweets. For example, you can include text and a video (or up to 3 images) and create a promoted Tweet.

Each line item needs to have at least one creative associated with it in order to run. Several options for creatives are available, including Promoted Accounts for gaining new followers, Media Creatives such as an image or video for line items across the TX Audience Platform, or Promoted Posts.

## Funding Instruments

Also under the ads account are funding instruments, which are the different sources of funding the advertiser has set up to use with X Ads. These span from insertion orders that they’ve signed with X to a credit card that is attached to the account.

## Line Items

Within a campaign, you can have one or more ad groups, also known as line items in the Ads API. Line items can be thought of as different segments of a campaign, each with its own targeting set and its own creative. Campaigns that contain multiple line items are often referred to as “ad group campaigns”.

One of the benefits of multiple line items within a single campaign is that you can create a greater variety of targeting and creative combinations.

Under our “Furni home decor” campaign, we might want to create two line items: one could be “Home buyers in San Francisco”, and the other could be “Home buyers in London”.

Up to 100 line items are allowed per campaign, and an ads account is limited to 4,000 active line items in total across all campaigns.

## Mobile App Promotion (MAP)

Mobile App Promotion, or MAP, is a suite of products that enable advertisers to promote mobile apps via X These include app installs, conversions and re-engagement.

## Mobile App Conversion Tracking (MACT)

X mobile app promotion measurement allows advertisers to track the success of advertising campaigns on X that are designed to drive installs or other in-app conversions. An X mobile measurement partner provides the ability for an advertiser to manage what conversions they want to track from the apps they are promoting on X. MACT Overview

## Media Library

The Media Library endpoints provide the ability to manage images, GIFs, and videos for X Ads accounts. Media assets in the library can be used in posts and to create cards. They can also be reused in multiple creatives, eliminating the need to upload the same asset multiple times.

## Promoted Accounts

Promoted Accounts (followers campaigns) are part of Who to Follow, which suggests accounts that people don’t currently follow and may find interesting. Promoted Accounts help introduce an even wider variety of accounts people may enjoy.

Promoted Accounts allow advertisers to promote their account and grow their audience on X. Follower campaigns are displayed in multiple locations across the X platform — including Home Timelines, Who to Follow, and search results — and this suggestion is labeled as Promoted to distinguish it from other recommended accounts.

## Promotable Users

Each X Ads account can have one or more promotable users, which are users that we can promote through the ads account. Furni’s @Furni handle would be an example of a FULL promotable user under Furni’s ads account, which means we can run all types of campaigns for @Furni and their tweets. There can only be one FULL promotable user for an ad account.

Note there can also be other promotable users under an ads account. For example, if we wanted to promote @Jack’s Tweets about Furni products, he would become a retweet-only promotable user on the account which is indicated by RETWEETS\_ONLY. Advertisers should contact their X account manager for information about adding reweet users to their ads account.

## Promoted Video

Promoted videos are videos within Promoted Tweets that are paid for by advertisers. These appear in the Home timeline, at the top of search results on X, and elsewhere on the platform, and are clearly marked as "Promoted”.

## Publisher Network

See [X Audience Platform](/x-ads-api/audiences).

## Scheduled Tweets

Scheduled Tweets allow an advertiser or user to create a Tweet that can be scheduled to go live at a later date. In addition to being able to create and manage these Tweets, the API allows the ability to associate these Tweets with a line item, to be promoted once the Tweet goes live. This allows advertisers to stage create native Tweets and plan their campaign creatives in advance of any key initiatives. For example, staging a Tweet creative to live immediately upon a new product announcement.

## Segmentation

Segmentation allows partners and advertisers to retrieve metrics broken out particular targeting values -- such as age, devices, or languages -- and is only available through our asynchronous analytics endpoints. To request segmented metrics, use the segmentation\_type request parameter. For more details on segmentation options, see Metrics and Segmentation.

## Tailored Audience - List

Tailored audiences from lists are one of three types of Tailored Audiences, created by uploading a file containing your own user and customer data. Your lists are matched with users on X so that you can directly target them in your campaigns. Please review these restrictions.

## Tailored Audience - Web

Tailored Audience from web, one of three types of Tailored Audiences, is a collection X users who have visited your website. To use Tailored Audiences from web you must have our X pixel installed on your website, or use one of our accepted tag manager partners. Please review these restrictions.

## Targeting Criteria

As we mentioned previously, targeting criteria are associated with a line item. We have a variety of different targeting that you can use, from location, keywords, and gender to more granular attributes, such as user behaviors and interests. For the “Home Buyers in San Francisco” line item, we might target the “home buying” behavior along with the “San Francisco” location.

For information on the different types of targeting available, visit the Targeting Overview page on our developer site.

## Twitter Object Nest (TON)

The Twitter Object Nest (TON) holds media and various assets upload via the Media Upload endpoints to be used as Creatives.

## Creatives

Each line item needs to have at least one creative associated with it in order to run. Several options for creatives are available, including Promoted Accounts for gaining new followers, Media Creatives such as an image or video for line items across the X Audience Platform, or Promoted Posts. Here’s an example post that @Furni could promote and use as a creative.


# Making Authenticated Requests
Source: https://docs.x.com/x-ads-api/fundamentals/making-authenticated-requests

How to make authenticated X Ads API requests over HTTPS using OAuth 1.0a, including Twurl setup, HTTP verbs, in-line parameters, and URL encoding rules.

Accessing the X Ads API endpoints requires your application to send authenticated web requests securely using TLS to [https://ads-api.x.com](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.

## Requirements

Before making authenticated requests to the X Ads API, you will need:

* an [approved developer account](/resources/fundamentals/developer-portal)
* an application that has been [approved for Ads API](/x-ads-api/introduction) access
* API key and secret obtained through the [app management UI](/resources/fundamentals/developer-apps) and
* [access tokens](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) for a user with access to a X Ads account

## Using the API

The Advertising API is accessed on [https://ads-api.x.com](https://ads-api.x.com). The [standard REST API](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/overview), and the Advertising API can be used together with the same client app. The Advertising API enforces HTTPS, therefore attempts to access an endpoint with HTTP will result in an error message.

The Ads API outputs JSON. All identifiers are strings and all strings are UTF-8. The Advertising API is [versioned](/x-ads-api/fundamentals/versioning) and the version is specified as the first path element of any resource URL.

`https://ads-api.x.com/<version>/accounts`

## HTTP verbs & typical response codes

There are four HTTP verbs used in the Ads API:

* **GET** retrieves data 
* **POST** creates new data, such as campaigns
* **PUT** updates existing data, like line items
* **DELETE** removes data.

While deletions are permanent, deleted data can still be viewed from most GET-based methods by including an explicit `with_deleted=true` parameter when asking for the resource. Otherwise, deleted records will return an HTTP 404.

A successful request will return an HTTP 200-series response along with the JSON response representing the object when creating, deleting, or updating a resource.

When updating data with HTTP PUT, only the specified fields will be updated. You can un-set an optional value by specifying the parameter with an empty string. As an example, this group of parameters would unset any already specified `end_time`: `&end_time=&paused=false`.

See [Error Codes & Responses](/x-ads-api/fundamentals/error-codes-and-responses) for more details on error responses.

## In-line parameters

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

The X Ads API uses signed HTTPS requests to validate an application’s identity and also obtain the permissions granted to the end-user that the application is making API request on behalf of, represented by the user's access token. All HTTP calls to the Ads API must include an Authorization request header (using OAuth 1.0a) over the HTTPS protocol.

You will need to add support to generate OAuth 1.0a Authorization request headers to your application to integrate with the X Ads API. However, due to the complexity of generating signed requests, we strongly recommended that partners use an existing library that either supports the X API or implements OAuth 1.0a request handling - here is a list of [recommended OAuth libraries](/resources/fundamentals/authentication#oauth-1-0a-2) and [authentication code samples](/resources/fundamentals/authentication#oauth-1-0a-2).

Note we can assist partners that encounter authentication errors when using a known library but cannot support custom OAuth implementations.

## HTTP & OAuth

Like X REST API v1.1, the Advertising API requires the use of both [OAuth 1.0A](/resources/fundamentals/authentication) and HTTPS. API keys can be obtained through the [app management console](/resources/fundamentals/developer-apps). Access tokens must also be used to represent the “current user.” The current user is a X account with advertising capabilities.

It is strongly recommended that partners use an OAuth library, rather than writing your own. We can support debugging when using a known library, but cannot if you roll your own OAuth implementation. See the [libraries](/resources/fundamentals/authentication#oauth-1-0a-2) that you can use.

The API is strict with HTTP 1.1 and OAuth. Ensure that you’re [encoding reserved characters](https://tools.ietf.org/html/rfc3986#section-2.2) appropriately within URLs and POST bodies before preparing OAuth signature base strings. The Advertising API in particular uses ”:” characters when specifying time and ”,” characters when providing a collection of options. Both characters are among this reserved set:

| Symbol | URL Encoded |
| :----- | :---------- |
| !      | %21         |
| #      | %23         |
| \$     | %24         |
| &      | %26         |
| '      | %27         |
| (      | %28         |
| )      | %29         |
| \*     | %2A         |
| +      | %2B         |
| ,      | %2C         |
| /      | %2F         |
| :      | %3A         |
| ;      | %3B         |
| =      | %3D         |
| ?      | %3F         |
| @      | %40         |
| \[     | %5B         |
| ]      | %5D         |

## Making your first API request with Twurl

X helps maintain a command-line tool, [Twurl](https://developer.x.com/en/docs/tutorials/using-twurl), that supports OAuth 1.0a authorization headers as an alternative to [cURL](https://en.wikipedia.org/wiki/CURL). Twurl provides a simple way of making authenticated API requests and exploring the Ads API before adding authentication to your application.

After [installing and authorizing Twurl](https://github.com/twitter/twurl#getting-started), you can quickly generate access tokens and make authenticated requests to the Ads API.

```bash theme={null}
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/reference#creating-a-campaign-step-by-step) tutorial for creating a campaign through the API.

## Testing with Postman

For those who are not familiar with a command-line tool, we also provide a Postman collection for the X Ads API endpoints.

[Postman](https://www.getpostman.com/products) is one of the most popular API development tools that exist in the industry nowadays. It’s an HTTP client that has a great user interface that lets you make a complex API request easier and increases productivity.

To install Postman and start using the Ads API Postman collection, please see our [set up guide](https://github.com/xdevplatform/postman-twitter-ads-api#installation).

<Button href="https://app.getpostman.com/run-collection/369a02c0adc626ff6a06#?env%5BTwitter%20Ads%20API%5D=W3sia2V5IjoiYWNjb3VudF9pZCIsInZhbHVlIjoieW91cl9hZHNfYWNjb3VudF9pZCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidmVyc2lvbiIsInZhbHVlIjoiNiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfa2V5IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX2tleSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfc2VjcmV0IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX3NlY3JldCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYWNjZXNzX3Rva2VuIiwidmFsdWUiOiJ5b3VyX2FjY2Vzc190b2tlbiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidG9rZW5fc2VjcmV0IiwidmFsdWUiOiJ5b3VyX3Rva2VuX3NlY3JldCIsImVuYWJsZWQiOnRydWV9XQ==">
  Run in Postman
</Button>

### Extending your application to make authenticated requests

After getting familiar with making requests to the Ads API using Twurl, it is time to add support to create OAuth 1.0a authentication headers to your application.

[OAuth 1.0a](/resources/fundamentals/authentication) authentication headers include information that verifies both the application’s and user's identity as well as prevents tampering with the request. Your application will need to create a new Authorization header for each API request. Many languages have open source libraries that support creating this authorization header to make API requests to X.

Here are some examples using C#, PHP, Ruby, and Python - [code samples](/resources/fundamentals/authentication#oauth-1-0a-2).

## Custom implementation

There are some scenarios that require implementing OAuth 1.0a authentication without the support of an open-source library. [Authorizing a request](/resources/fundamentals/authentication#authorizing-a-request) provides detailed instructions for implementing support for creating the Authorization header. We strongly recommend using a community-supported library.

General outline:

1. Collect 7 key/value pairs for the header - starting with oauth\_
2. Generate an [OAuth 1.0a HMAC-SHA1 signature](/resources/fundamentals/authentication#creating-a-signature) using those key/value pairs
3. Build the [Authorization header](/resources/fundamentals/authentication#authorizing-a-request) using the above values


# Pagination
Source: https://docs.x.com/x-ads-api/fundamentals/pagination

How to paginate large result sets on X Ads API GET endpoints using cursor and count query parameters with the next_cursor token to fetch subsequent pages.

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).

## Getting started

For designated GET requests, we now accept `cursor` and `count` query parameters, which are both optional. If a response has more than `count` entities, these endpoints will now return the first `count` entities and a `next_cursor` key in the response JSON.

`GET https://ads-api.x.com/5/accounts/abc1/campaigns?count=50`

```json theme={null}
{
  "data": \[...\],
  "next_cursor": "c-3yvu1pzhd3i7",
  "request": {...}
}
```

To get the next series of responses, you would add `cursor` to your query params:

`GET https://ads-api.x.com/5/accounts/abc1/campaigns?cursor=c-3yvu1pzhd3i7&count=50`

```json theme={null}
{
  "data": \[...\],
  "next_cursor": "c-3w3zdyg8ywan",
  "request": {...}
}
```

## Going deeper

For most endpoints, the maximum `count` value is **1,000**, the minimum is **1**, and the default is **200**.

The value provided by `next_cursor` is always a string, and should be considered opaque; the implementation is subject to change. If less than `count` entities are returned in the current page of the result set, the `next_cursor` value will be `null`.

**Note:** the analytics endpoints do not support this style of pagination. Paging on the stats endpoints is supported by specifying periods of time. See the documentation of those individual endpoints for more information.


# Rate limiting
Source: https://docs.x.com/x-ads-api/fundamentals/rate-limiting

The Advertiser API is rate limited similarly to REST API v1.1, as documented here: REST API Rate Limiting in v1.1. Unlike REST API v1.1, there is no.

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.

## User level and ad account level limits

There are two types of rate limits: user token level and ad account level. A subset of endpoints are enabled to use ad account level rate limiting. A user token is the [OAuth access token](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) you use to authenticate and call the Ads API. Each user token can have access to one or more ad accounts.

Developers should utilize the ad account level rate limit when it is returned in response headers and only utilize user level limit when the ad account limit is not found.

User level rate limits are expressed via these headers: **x-rate-limit-limit**, **x-rate-limit-remaining** and **x-rate-limit-reset**

For endpoints with ad account rate limiting enabled, the rate limits are expressed via these headers: **x-account-rate-limit-limit**, **x-account-rate-limit-remaining** and **x-account-rate-limit-reset**.

The ad account level rate limits are provided only for GET endpoints to enable applications to synchronize entity data (such as campaign or line item objects) from a single user token accessing multiple ad accounts. Write actions are not guaranteed to use the same ad account level rate limits.

For ad account level rate limited endpoints, the user level rate limit is set at a high value representing a global quota for your entire application. When available the ad account level rate limit should take precedence in controlling your request volume.

## Best practices

1. Save a timestamp in your database with the last synced timestamp, and when requesting data where applicable request data with `sort_by=updated_at-desc` option to enable you to stop your syncing process after reaching data older than your last synced timestamp. This will avoid syncing the same data redundantly.

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/reference#targeting-criteria) are strongly recommended to call with maximum count value to return 1000 objects instead of the default of 200.

## Analytics syncing

See the [Analytics Rate Limiting Guide](/x-ads-api/analytics#best-practices) for more information about analytics endpoint rate limits.

## FAQs

*Is it possible to increase rate limits for a particular ad account or our application?*

We generally cannot raise rate limits and they are set to support the largest of ad accounts. Please implement the Best Practices listed in this document as a first step, and if rate limits are still impacting your ability to scale or achieve business objectives please reach out to your X Ads API contacts with complete details about the use case and requests involved.

## Scopes of rate limiting

### Scopes for this doc

* Category: all endpoints that fall into the given category are rate limited from a single allocated limit per window.
* Endpoint: each endpoint has its own distinct allocated limit per window.

## Ads API rate limit chart

### Ads API rate limits

| Endpoint Type              | Scope by Endpoint or Category | Rate Limit per 1-minute window |
| :------------------------- | :---------------------------- | :----------------------------- |
| Writes (POST, PUT, DELETE) | Category                      | 450                            |
| Audience                   | Endpoint                      | 1500                           |

| Endpoint Type                                                                                                         | Scope by Endpoint or Category                                              | Rate Limit per 15-minute window |
| :-------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | :------------------------------ |
| Analytics (synchronous)                                                                                               | Category                                                                   | 250                             |
| Core Entity Reads (Line Items, Campaigns, etc)<br /><br />Other Account Reads (Other GET endpoints with :account\_id) | Endpoint (Ad Account Level)<br /><br />Endpoint (Partial Ad Account Level) | 10,000<br /><br />2000          |
| Targeting Criteria (besides below)                                                                                    | Category                                                                   | 400                             |
| Targeting Criteria (tv\_markets, tv\_shows)                                                                           | Endpoint                                                                   | 2000                            |
| Audience Insights                                                                                                     | Category                                                                   | 400                             |
| Keyword Insights                                                                                                      | Category                                                                   | 500                             |
| Global Reads (GET endpoints without :account\_id)                                                                     | Endpoint                                                                   | 5                               |
| Conversions                                                                                                           | Endpoint                                                                   | 60,000                          |


# Sandbox
Source: https://docs.x.com/x-ads-api/fundamentals/sandbox

Use the X Ads API sandbox environment to safely test campaign workflows, create test advertiser accounts, and manage funding instruments without serving ads.

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


# Sorting
Source: https://docs.x.com/x-ads-api/fundamentals/sorting

Sort X Ads API collection results using the sort_by query parameter, with supported ascending and descending attributes for campaigns, line items, and more.

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

In your API request simply append `sort_by=[attribute name]-[asc/desc]` where the attribute is a valid attribute that is returned in the JSON of your GET request.

For example, you can use `?name-asc` to sort by name alphabetically or `?name-desc` to sort in reverse.

## Going deeper

Below is a sample API request to return all line items by the `bid_amount_local_micro` in descending order:

`twurl -H ads-api.x.com "/5/accounts/k9w0oe/line\_items?sort\_by=bid\_amount\_local_micro-desc"`

```json theme={null}
{
  "request": {
    "params": {
      "sort_by": \[
        "bid\_amount\_local_micro-desc"
      \],
      "account_id": "k9w0oe"
    }
  },
  "data": \[
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 3000000,
      "automatically\_select\_bid": false,
      "advertiser_domain": null,
      "primary\_web\_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product\_type": "PROMOTED\_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total\_budget\_amount\_local\_micro": null,
      "objective": "ENGAGEMENTS",
      "id": "1iw6k",
      "paused": true,
      "optimization": "DEFAULT",
      "categories": \[

      \],
      "currency": "USD",
      "created_at": "2014-09-09T02:11:32Z",
      "updated_at": "2015-05-27T23:01:45Z",
      "include\_sentiment": "POSITIVE\_ONLY",
      "campaign_id": "1kv71",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 3000000,
      "automatically\_select\_bid": false,
      "advertiser_domain": null,
      "primary\_web\_event_tag": null,
      "charge_by": "FOLLOW",
      "product\_type": "PROMOTED\_ACCOUNT",
      "bid_unit": "FOLLOW",
      "total\_budget\_amount\_local\_micro": null,
      "objective": "FOLLOWERS",
      "id": "1nlqp",
      "paused": false,
      "optimization": "DEFAULT",
      "categories": \[

      \],
      "currency": "USD",
      "created_at": "2014-10-20T18:57:18Z",
      "updated_at": "2014-10-20T18:57:18Z",
      "include_sentiment": null,
      "campaign_id": "1pjkp",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 2500000,
      "automatically\_select\_bid": false,
      "advertiser_domain": null,
      "primary\_web\_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product\_type": "PROMOTED\_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total\_budget\_amount\_local\_micro": null,
      "objective": "ENGAGEMENTS",
      "id": "1iw6l",
      "paused": true,
      "optimization": "DEFAULT",
      "categories": \[

      \],
      "currency": "USD",
      "created_at": "2014-09-09T02:11:54Z",
      "updated_at": "2014-09-17T06:23:23Z",
      "include\_sentiment": "POSITIVE\_ONLY",
      "campaign_id": "1kv71",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 2500000,
      "automatically\_select\_bid": false,
      "advertiser_domain": null,
      "primary\_web\_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product\_type": "PROMOTED\_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total\_budget\_amount\_local\_micro": null,
      "objective": "ENGAGEMENTS",
      "id": "1iw9q",
      "paused": false,
      "optimization": "DEFAULT",
      "categories": \[

      \],
      "currency": "USD",
      "created_at": "2014-09-09T03:11:46Z",
      "updated_at": "2014-09-09T03:26:17Z",
      "include\_sentiment": "POSITIVE\_ONLY",
      "campaign_id": "1kv71",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 2500000,
      "automatically\_select\_bid": false,
      "advertiser_domain": null,
      "primary\_web\_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product\_type": "PROMOTED\_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total\_budget\_amount\_local\_micro": null,
      "objective": "ENGAGEMENTS",
      "id": "1iw9r",
      "paused": false,
      "optimization": "DEFAULT",
      "categories": \[

      \],
      "currency": "USD",
      "created_at": "2014-09-09T03:12:02Z",
      "updated_at": "2014-09-09T03:30:44Z",
      "include\_sentiment": "POSITIVE\_ONLY",
      "campaign_id": "1kv71",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": \[
        "TWITTER_TIMELINE",
        "TWITTER_PROFILE"
      \],
      "bid\_amount\_local_micro": 2000000,
      "automatically\_select\_bid": false,
      "advertiser_domain": null,
      "primary\_web\_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product\_type": "PROMOTED\_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total\_budget\_amount\_local\_micro": null,
      "objective": "ENGAGEMENTS",
      "id": "1kkze",
      "paused": false,
      "optimization": "DEFAULT",
      "categories": \[

      \],
      "currency": "USD",
      "created_at": "2014-09-24T01:18:20Z",
      "updated_at": "2015-08-30T04:41:34Z",
      "include_sentiment": null,
      "campaign_id": "1mj4h",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": \[
        "TWITTER_TIMELINE",
        "TWITTER_PROFILE"
      \],
      "bid\_amount\_local_micro": 2000000,
      "automatically\_select\_bid": false,
      "advertiser_domain": null,
      "primary\_web\_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product\_type": "PROMOTED\_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total\_budget\_amount\_local\_micro": null,
      "objective": "ENGAGEMENTS",
      "id": "1kkzk",
      "paused": false,
      "optimization": "DEFAULT",
      "categories": \[

      \],
      "currency": "USD",
      "created_at": "2014-09-24T01:23:06Z",
      "updated_at": "2015-08-30T04:41:34Z",
      "include_sentiment": null,
      "campaign_id": "1mj4n",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 2000000,
      "automatically\_select\_bid": false,
      "advertiser_domain": null,
      "primary\_web\_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product\_type": "PROMOTED\_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total\_budget\_amount\_local\_micro": null,
      "objective": "ENGAGEMENTS",
      "id": "1kkzq",
      "paused": false,
      "optimization": "DEFAULT",
      "categories": \[

      \],
      "currency": "USD",
      "created_at": "2014-09-24T01:25:06Z",
      "updated_at": "2014-09-24T01:34:20Z",
      "include\_sentiment": "POSITIVE\_ONLY",
      "campaign_id": "1mj48",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 2000000,
      "automatically\_select\_bid": false,
      "advertiser_domain": null,
      "primary\_web\_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product\_type": "PROMOTED\_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total\_budget\_amount\_local\_micro": null,
      "objective": "ENGAGEMENTS",
      "id": "1kkzr",
      "paused": false,
      "optimization": "DEFAULT",
      "categories": \[

      \],
      "currency": "USD",
      "created_at": "2014-09-24T01:25:09Z",
      "updated_at": "2014-09-24T01:34:41Z",
      "include\_sentiment": "POSITIVE\_ONLY",
      "campaign_id": "1mj48",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 2000000,
      "automatically\_select\_bid": false,
      "advertiser_domain": null,
      "primary\_web\_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product\_type": "PROMOTED\_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total\_budget\_amount\_local\_micro": 6000000,
      "objective": "ENGAGEMENTS",
      "id": "1kl0e",
      "paused": false,
      "optimization": "DEFAULT",
      "categories": \[

      \],
      "currency": "USD",
      "created_at": "2014-09-24T01:42:49Z",
      "updated_at": "2014-09-24T01:51:25Z",
      "include\_sentiment": "POSITIVE\_ONLY",
      "campaign_id": "1mj57",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 2000000,
      "automatically\_select\_bid": false,
      "advertiser_domain": null,
      "primary\_web\_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product\_type": "PROMOTED\_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total\_budget\_amount\_local\_micro": 12000000,
      "objective": "ENGAGEMENTS",
      "id": "1kl0g",
      "paused": false,
      "optimization": "DEFAULT",
      "categories": \[

      \],
      "currency": "USD",
      "created_at": "2014-09-24T01:43:19Z",
      "updated_at": "2014-09-24T01:51:40Z",
      "include\_sentiment": "POSITIVE\_ONLY",
      "campaign_id": "1mj57",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 2000000,
      "automatically\_select\_bid": false,
      "advertiser_domain": null,
      "primary\_web\_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product\_type": "PROMOTED\_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total\
```


# Timezones
Source: https://docs.x.com/x-ads-api/fundamentals/timezones

How the X Ads API handles timezones for accounts and billing, including ISO 8601 datetime formats, UTC offsets, and timezone_switch_at analytics implications.

## 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/reference#accounts)), you will get timezone information that looks like this:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "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",
        "salt": "54cb7b5a34183f77d82dd6d0f4329691",
        "updated_at": "2017-09-09T06:42:14Z",
        "business_id": null,
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }
```

This includes two timezone values: `timezone` (see [timezones at wikipedia](https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones) for an overview) and `timezone_switch_at`. Note that `timezone_switch_at` is given in the UTC timezone (+00:00), but will always represent midnight in the given timezone.

The advertiser’s timezone is not editable via the API. This attribute is set at the contractual/billing level by the advertiser’s account manager at X.

Please be aware of the `timezone_switch_at` value when creating reports and querying our analytics endpoints as there will be a gap on the day the account switches from the America/Los\_Angeles timezone to the new local value.

### Specifying Datetime Values With Timezone

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](http://en.wikipedia.org/wiki/ISO_8601) format for timezone. For example, `2017-07-10T08:00:00-0800` is an acceptable input value and will be automatically translated to the UTC value of `2017-07-10T16:00:00Z`.

When using the analytics endpoints with `granularity` of `DAY` or `TOTAL`, the `start_time` value must be specified at midnight of the desired day in the local timezone of the account holder. The timezone offset to be used will be the offset of the current day, not the offset of the day in question. For example, for an ads account in America/Los\_Angeles during Pacific Daylight Savings time, the UTC offset is -0700. Thus, in an analytics request, the time should be specified as: `start_time=2017-05-21T07:00:00Z` or `start_time=2017-05-21T00:00:00-0700`. If the ads account was in Asia/Tokyo, where the offset is always +09:00, the values would be specified as: `start_time=2017-05-20T15:00:00Z` or `start_time=2017-05-21T00:00:00+0900`.

### Accepted UTC Offset Formats

See [ISO 8601 Time zone designators](http://en.wikipedia.org/wiki/ISO_8601#Time_zone_designators).

Supported: `Z`, `-HHMM`, `+HHMM`, `-HH:MM`, `+HH:MM`, `-HH`, `+HH`


# Versions
Source: https://docs.x.com/x-ads-api/fundamentals/versioning

History of X Ads API versions with release, deprecation, and end of life dates, plus the versioning strategy covering breaking changes and migration windows.

For the most up to date information on historical versions of the X Ads API, please reference the information below.

| Version                                                        | Path | Introduction Date | Deprecated Date   | End of Life Date  |
| :------------------------------------------------------------- | :--- | :---------------- | :---------------- | :---------------- |
| [12.0](#)                                                      | /12/ | October 27, 2022  | TBD               | TBD               |
| [11.0](https://devcommunity.x.com/t/ads-api-version-11/168814) | /11/ | March 31, 2022    | TBD               | TBD               |
| [10.0](#v9)                                                    | /10/ | August 31, 2021   | March 31, 2022    | October 27, 2022  |
| [9.0](#v9)                                                     | /9/  | March 2, 2021     | August 31, 2021   | March 31, 2022    |
| [8.0](#v8)                                                     | /8/  | September 8, 2020 | March 2, 2021     | August 31, 2021   |
| [7.0](#v7)                                                     | /7/  | March 3, 2020     | September 1, 2020 | March 2, 2021     |
| [6.0](#v6)                                                     | /6/  | August 28, 2019   | March 3, 2020     | September 1, 2020 |
| [5.0](#v5)                                                     | /5/  | February 28, 2019 | August 28, 2019   | March 3, 2020     |
| [4.0](#v4)                                                     | /4/  | August 28, 2018   | February 28, 2019 | August 28, 2019   |
| [3.0](#v3)                                                     | /3/  | February 1, 2018  | August 28, 2018   | February 28, 2019 |
| [2.0](#v2)                                                     | /2/  | July 10, 2017     | February 1, 2018  | August 1, 2018    |
| [1.0](#v1)                                                     | /1/  | March 31, 2016    | July 7, 2017      | January 10, 2018  |
| [0.0](#v0)                                                     | /0/  | February 21, 2013 | N/A               | October 31, 2016  |

## Overview

Every month, we make changes and roll out several new features on the X Ads API. These changes are nearly always backwards compatible, however we do tend to have a handful of breaking changes each year. We’ve received feedback from developers on the challenges that our fast cadence of changes in the Ads API has on their development cycles when it comes to implementing new features, handling deprecations and testing changes. We want to improve the developer experience using our Ads platform, which is why we introduced the concept of versioning our endpoints.

A few definitions of some of the concepts that we talk about:

**Version**: This refers to the version number found in the URL path of any Ads API request, for example: GET //accounts.  This style of versioning is known as URI versioning.

**Breaking Changes**: Breaking changes are any changes that require developer resources to maintain existing functionality. This includes resources used for investigation into the changes that need to be made, determination of features/endpoints being deprecated and final implementation of all these changes. A list of breaking changes are things like:

* Removing a param from the API request/response

* Modifying the name for any params or endpoints

* Change in the representation of values (preview\_url → card\_uri)

* Change in behavior of endpoints (e.g.,  async vs sync stats)

* Adding/changing optional or required params (e.g., making name a required field in the request)

**Deprecation**: Deprecated versions or products will be unsupported and it is recommended that developers cease to use these APIs.

**Sunset**: Once a product or API is sunset, the corresponding set of endpoints will no longer be accessible via the API.

## Versioning strategy

The main principles of the strategy are:

1. All breaking changes will be bundled into a new version

2. Deprecations for existing versions whenever a new version is announced is 6 months

3. At any given time, the API will allow requests from two versions simultaneously, however the older of the two will be unsupported

4. In order to provide quicker adoption of new products, these will be released on an ongoing basis (outside of the versioning cadence)

5. All API responses will contain a `x-current-api-version` which will be set to the current version of the API in addition to an `x-api-warn` header when calling any deprecated API endpoints.

Should there be any fundamental product requirement changes that require an API breaking change (e.g. deprecating multiple age bucket targeting), we will send out a 90-day notice to announce this breaking change, and after at least 90 days after the notice is released, the breaking change will be deployed

### v9

Today, March 3rd, 2021, Version 9 (v9) of the X Ads API is now available. This release is designed to increase feature parity, simplify campaign creation, and to introduce key updates to our Cards and Mobile App Promotion endpoints.

As with our previous versions, there will be a 6 month transition period to migrate to v9. On August 31, 2021, the existing version 8 (v8) of the Ads API will no longer be available. We encourage all developers to migrate to the latest version of the Ads API as soon as possible to avoid any service disruptions.

<Note>
  **Note:** As of this release, Version 7 (v7) of the Ads API has reached its end of life and is no longer available.
</Note>

For full details, please see the [announcement on the developer forum](https://devcommunity.x.com/t/ads-api-version-9/150316).

### v8

Today, September 20th, 2020, we introduce Version 8 of the X Ads API, designed to introduce new Tailored Audiences functionality, increase feature parity with ads.x.com, and improve your developer experience.

As with previous versions, there will be a 6 month transition period to migrate to v8. On 2021-03-02 version 7 of the Ads API will no longer be available. We encourage all developers to migrate to the latest version of the API as soon as possible to avoid any service disruptions.

For full details, please see the [announcement on the developer forum](https://devcommunity.x.com/t/ads-api-version-8/141914).

### v7

Today, March 20th, 2020, we introduce Version 7 of the X Ads API, designed to increase feature parity with [ads.x.com](http://ads.x.com/).

As with previous [versions](https://developer.x.com/en/docs/ads/general/overview/versions), there will be a 6 month transition period to migrate to v7. On 2020-09-01, version 6 of the Ads API will no longer be available. We encourage all developers to migrate to the latest version of the API as soon as possible to avoid any service disruptions. Version 5 of the Ads API has reached its end of life and is no longer available.

For full details, please see the [announcement on the developer forum](https://devcommunity.x.com/t/ads-api-version-7/135093).

### v6

Today, August 28, 2019, X is introducing Ads API v6, with updates that focus on consistency and improving the developer experience.

This release includes a new endpoint for retrieving Tweets, stats for Promoted Accounts, the ability to search for entities by name, and information about the current number of processing asynchronous analytics jobs. In addition, we’ve made consistency-focused updates to endpoints that use media and to our targeting criteria endpoints. Finally, we’ve made minor updates to some of our parameter names and response attributes and are deprecating the Scoped Timeline endpoint.

For full details, please see the [announcement on the developer forum](https://devcommunity.x.com/t/ads-api-version-6/129060).

### v5

Today, February 28, 2019, X introduces Ads API v5, with updates that focus on enabling scale and efficiency.

This release includes a new endpoint to determine which entities were active in a given timeframe, stats for Media Creatives (i.e., In-stream videos and images on the X Audience Platform), the ability to fetch *multiple* cards, by card URI, and more flexibility around retrieving targeting criteria and other entities. In addition, we’ve fixed some bugs and made updates to parameter names and response attributes. Finally, non-media app cards and the POST `accounts/:account_id/account_media` endpoint have been deprecated.

As with previous versions, there will be a 6 month transition period to migrate to v5. On **2019-08-28**, version 4 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. *Version 3 of the Ads API has reached its end of life and is no longer available.*

#### New

**Determining which entities were active**

The [Active Entities](/x-ads-api/analytics#active-entities-2) endpoint signifies whether analytics metrics for ads entities have changed. Designed to be used in conjunction with the analytics endpoints, Active Entities works by specifying an entity type and a date range—a maximum of 90 days—and returns an array of entity IDs that your platform should request analytics for. IDs other than the ones returned should not be queried in subsequent analytics requests.

This endpoint supports the following entity types:`CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `MEDIA_CREATIVE`, and `PROMOTED_TWEET`.

**`MEDIA_CREATIVE` stats**

The Ads API’s analytics endpoints now provide metrics for Media Creative entities. Media Creatives are how in-stream ads or images on the X Audience Platform are promoted. The X Ads UI shows Media Creative metrics under the “In-stream videos” and “Display creatives” tabs. Both [synchronous](/x-ads-api/analytics#get-stats-accounts-account-id) and [asynchronous](/x-ads-api/analytics#asynchronous-analytics) analytics endpoints now support the `MEDIA_CREATIVE` entity enum.

**Fetch multiple cards**

Improving on the [v3 release](https://devcommunity.x.com/t/ads-api-version-3/100732) of the endpoint designed to retrieve a single card by its card URI value, it’s now possible to fetch *multiple* cards using the [GET accounts/:account\_id/cards/all](/x-ads-api/creatives/reference#cards-fetch) endpoint. Now, rather than making a request for each card, you can retrieve up to 200 cards in a single request.

Two things to note:

1. The URL path is now `accounts/:account_id/cards/all`. (The previous path is no longer available.) This is so that we’re consistent with [the endpoint](/x-ads-api/creatives/reference#cards-fetch) designed to retrieve a card by ID.
2. The required request parameter is now named card\_uris (plural).

**Flexibility around retrieving**

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/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/reference#preroll-call-to-actions)

#### Changed

**Retrieving draft campaigns and line items**

The way that draft campaigns and line items are retrieved has been updated. Now, the with\_draft(boolean) parameter, when set to true, returns *both* draft and non-draft entities. This is consistent with the way deleted entities are retrieved (i.e., using with\_deleted). Previously, fetching both draft and non-draft entities required at least two requests. Now, this can be done in a single API call.

\| **v4** | **v5** |
\| :--- | :--- | :--- |
\| `draft_only` | `with_draft` |     |

**Network activation duration targeting**

The Ads API has resolved a display issue where, after adding Network Activation Duration targeting, th


# Increasing access
Source: https://docs.x.com/x-ads-api/getting-started/increasing-access

How to request additional X Ads API permissions, including Standard Access, expanded app-level permissions, and steps for upgrading your account.

### Requesting additional App-level permissions

If your application is limited to any of the below app-level permissions and you wish to access additional endpoints, please reach out to your X representative to apply for **Standard Access**.

Developers who requested Ads API access prior to July 2023 may have requested any of the following app-level permissions, which are now included with
the Standard Access level:

* **Analytics** (Read-only): User has access to [Analytics](https://developer.x.com/en/docs/twitter-ads-api/analytics/overview) endpoints with [read-only](https://developer.x.com/en/docs/apps/app-permissions) access. User cannot access Campaign Management, Creative or Custom Audiences endpoints, but will be able to pull metrics by passing through creative entities in the request parameters of the Analytics endpoints. To pull the granularity of media\_id or media\_name, the user application would need to have Ads API write access.

* **Campaign Management & Creative** (Read & Write): User has access to [Campaign Management](https://developer.x.com/en/docs/twitter-ads-api/campaign-management/overview) and [Creative](https://developer.x.com/en/docs/twitter-ads-api/creatives/overview) endpoints with [read & write](https://developer.x.com/en/docs/apps/app-permissions) access. User also has access to Analytics endpoints.

* **Custom Audiences** (Read & Write): User has access to [Custom Audiences](https://developer.x.com/en/docs/twitter-ads-api/audiences/overview) endpoints
  with [read & write](https://developer.x.com/en/docs/apps/app-permissions) access. User also has access to Campaign Management, Creative, and Analytics endpoints.

* **Conversion** (Read & Write): User has access to [Mobile](https://developer.x.com/en/docs/twitter-ads-api/measurement/mobile-conversions/overview) and [Web Conversion](https://developer.x.com/en/docs/twitter-ads-api/measurement/web-conversions/overview) endpoints with [read & write](https://developer.x.com/en/docs/apps/app-permissions) access. User may or may not have access to other Ads API endpoints.

### Requesting an increase to user OAuth token limits

Developers who requested Ads API access prior to July 2023 may have a limit of 5 user OAuth tokens on their application. If you need to increase your developer App's token limit, please reach out to your X representative.

<Note>**Note:** We do not increase the [rate limits](https://developer.x.com/en/docs/twitter-ads-api/rate-limiting) for any Ads API endpoint. View our [best practices](https://developer.x.com/en/docs/twitter-ads-api/rate-limiting) to learn how to stay within rate limits.</Note>


# Step-by-step guide
Source: https://docs.x.com/x-ads-api/getting-started/step-by-step-guide

Step-by-step guide to getting started with the X Ads API, including account setup, app creation, applying for access, and authenticating requests.

## How to get access to the Ads API

1. Sign up for a [developer account](https://console.x.com).
2. Create a [developer App](/fundamentals/developer-apps) and secure your token.
3. Submit a request for Ads API access for each of your developer app(s) using the [Ads API Access Form](/forms/ads-api-access).

<Note>**Note:** If you are already building on the X Developer Platform and have a developer account, skip to step three.</Note>

### Step one: Sign up for a developer account

To make a request to any of X's API products, you must first sign up for a developer account. Within the Developer Console, create an App and developer App. This will provide you a set of credentials that you will use to authenticate all requests to the API.

<Button href="https://console.x.com">
  Sign up for a developer account
</Button>

### Step two: Save your App's key and tokens and keep them secure

Within your developer App, you will be provided a set of API Keys (also known as Consumer Keys). You will also have the chance to generate a set of Access Tokens that can be used to make requests on behalf of your personal X account, and a Bearer Token that can be used to authenticate endpoints that require OAuth 2.0 Bearer Token. As these keys and tokens do not expire unless regenerated, we suggest creating environment variables, or using a secure password manager.

Please also take note of your App ID, which can be found in the URL of your App details. This will make it easier to request access to the Ads API in the next step.

<Note>
  **Note:** Your keys and tokens will only display once in the Developer Console, so it is important that you store these credentials in your password management system as soon as you generate them.

  If you misplace or forget the keys and tokens, you will need to regenerate them, which creates new keys and tokens, and invalidates the old ones. This means that you will have to update any integrations that you may have set up with your prior credentials.

  Learn more about our [authentication best practices](/fundamentals/authentication/guides/authentication-best-practices).
</Note>

### Step three: Apply for access to the Ads API

At this point you will have basic access to the X API, but not specific X Ads API functionality. Next, you will need to request access and be approved for Ads API access. Use the [Ads API Access Form](/forms/ads-api-access) to submit a request for each of your developer app(s).

### Access tiers

As part of the application process, you'll need to specify what level of access you require. Learn more about [App-level and Ad Account-level permissions](/x-ads-api/fundamentals/accessing-ads-accounts#levels-of-access).

#### Conversion Only

Access to Mobile and Web Conversion endpoints with read & write access.

#### Standard Access

Access to Analytics, Campaign Management, Creatives, Custom Audiences, and Conversion endpoints with read & write access.

<Note>**Note:** After your app is approved for Ads API access, you will need to [regenerate any user access tokens](/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) to make properly [authenticated Ads API requests](/x-ads-api/fundamentals/making-authenticated-requests).</Note>

<Note>**Note:** Ads API developers who requested access prior to July 2023 may have different levels of access and permissions, and may be limited to five OAuth tokens. See our guide on [increasing access](/x-ads-api/getting-started/increasing-access) to access to additional endpoints or lift token limits for existing applications.</Note>

## Make your first request

To test your access to the Ads API make a request to the [GET accounts](/x-ads-api/campaign-management/reference#get-accounts) endpoint. This endpoint will return the ad accounts the currently authorized user has access to. Use the ad account IDs from this request in subsequent API requests to read and write data for a specific ad account. Using [Twurl](https://github.com/twitter/twurl) on the command line the request would look like the following.

**Example Request**

```bash theme={null}
twurl -H ads-api.x.com "/11/accounts"
```

**Example Response**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "request": {
    "params": {}
  },
  "data": [
   {
    "name": "Furni",
    "business_name": null,
    "timezone": "America/Los_Angeles",
    "timezone_switch_at": "2016-04-06T07:00:00Z",
    "id": "18ce54ayf0z",
    "created_at": "2016-04-07T14:40:15Z",
    "salt": "b88939e5cabbca720159cb3659d73c06",
    "updated_at": "2017-02-08T08:49:53Z",
    "business_id": null,
    "approval_status": "ACCEPTED",
    "deleted": false
     }
   ]
}
```

## Up next . . .

* Read through the [Ads API documentation](/x-ads-api/introduction) fundamentals such as [versioning](/x-ads-api/fundamentals/versioning) and [hierarchy](/x-ads-api/fundamentals/hierarchy-and-terminology).
* Check out the various [Ads API tools & libraries](/x-ads-api/tools-and-libraries) to aid you in your Ads API integration.
* Understand the steps to [increase Ads API access](/x-ads-api/getting-started/increasing-access).
* Familiarize yourself with available [support resources](/support).
* Follow [@API](https://x.com/API) for live updates on API changes, service issues and enhancements to X promoted products.


# Subscribe for updates
Source: https://docs.x.com/x-ads-api/getting-started/subscribe-for-updates

Subscribe to email updates about the X Ads API, including new features, deprecations, breaking changes, and product announcements for advertisers.



# X Ads API for campaign, audience, and creative management
Source: https://docs.x.com/x-ads-api/introduction

Use the X Ads API to programmatically manage ad campaigns, audiences, creatives, and reporting on the X advertising platform with OAuth-authenticated endpoints.

## Connect to the X Ads platform

The X Ads API connects developers to X's advertising platform to build solutions to meet the needs of X's advertisers around the world.

<Button href="/x-ads-api/getting-started">
  Get started
</Button>

***

<CardGroup>
  <Card title="Campaign management" icon="list-check" href="/x-ads-api/campaign-management">Programmatically create, schedule, and manage ad campaigns to engage people on X.</Card>
  <Card title="Custom audiences" href="/x-ads-api/audiences" icon="user-group">Create and manage Tailored Audiences using X, web or mobile data you provide.</Card>
  <Card title="Creatives" href="/x-ads-api/creatives" icon="paintbrush">Draft and publish posts, extend the functionality of posts with Cards and manage and upload images and videos.</Card>
  <Card title="Advertising analytics" href="/x-ads-api/analytics" icon="chart-pie">Use async and synchronous API endpoints to retrieve granular insights of ad campaigns by a full range of metrics.</Card>
  <Card title="Tools and libraries" href="/x-ads-api/tools-and-libraries" icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-wrench.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=c3f1761285cd013a76037d1d537f10ed">Check out our curated selection of X-built and community-supported client libraries.</Card>
  <Card title="Postman collection" href="https://documenter.getpostman.com/view/7379786/SzRw1WTU" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219">Explore our v2 endpoints with a curated Postman collection and visual client.</Card>
  <Card title="Command line tool" href="https://github.com/xdevplatform/xurl" icon="terminal">Work with our endpoints from your terminal using xurl.</Card>
</CardGroup>

## Get Ads API access

To request Ads API access, submit the [Ads API Access Form](/forms/ads-api-access). Allow up to 3 business days for review.

## Need help?

Visit our support section for troubleshooting tips, contact details, a live API status monitor, and other resources.

[Visit the Ads API support section](https://developer.x.com/en/support/twitter-ads-api.html)

***

Help us build the next generation of the X API: [Give us your product feedback >](https://twitterdevfeedback.uservoice.com/forums/930250-twitter-api)


# AB Testing
Source: https://docs.x.com/x-ads-api/measurement/ab-testing

Run A/B tests on X Ads campaigns to compare creatives, targeting, bid type, and bid unit variations across randomized user group splits and measure lift.

## Overview

### Introduction

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 gather learnings to inform their marketing strategies.

These segments—referred to as user group splits—are randomized and mutually exclusive. With randomization, factors that influence outcomes are equally distributed. In other words, there are no inherent differences between groups or their expected behaviors. Because of this, when a single variation is applied to a user group and not the others, the difference in campaign performance can be attributed to that variation.

While it's possible to test many variations at once, we strongly recommend testing a single variation at a time. This isolates the causal factor for the observed difference in campaign performance.

Variations are set at the campaign level. For example, if the advertiser wants to test the efficacy of a new creative, they should create two identical campaigns where the only difference is the creative. In the future, we plan to support variations at the line item level.

### Use Cases

A/B testing is most often used to support (1) optimization use cases for performance customers who want to understand what works best on X in order to optimize their investment and (2) learning use cases for brand advertisers who want to use learnings to inform their marketing strategy. 

The API will support A/B testing for any campaign variable, including:

* Creative 

* Targeting 

* Bid type

* Bid unit

## A/B Testing

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 gather learnings to inform their marketing strategies.

These segments—referred to as user group splits—are randomized and mutually exclusive. With randomization, factors that influence outcomes are equally distributed. In other words, there are no inherent differences between groups or their expected behaviors. Because of this, when a single variation is applied to a user group and not the others, the difference in campaign performance can be attributed to that variation.

While it's possible to test many variations at once, we strongly recommend testing a single variation at a time. This isolates the causal factor for the observed difference in campaign performance.

Variations are set at either the campaign level or the ad group level. The ad group is set through [line item](https://developer.x.com/en/docs/twitter-ads-api/campaign-management/api-reference/line-items) in Ads API,  As an example of an ad group level variation, if the advertiser wants to test the efficacy of a new creative, they should create one campaign with 2 identical ad groups where the only difference is the creative.

### Use Cases

A/B testing is most often used to support (1) optimization use cases for performance customers who want to understand what works best on X in order to optimize their investment and (2) learning use cases for brand advertisers who want to use learnings to inform their marketing strategy. 

The API will support A/B testing for any campaign variable, including:

* Creative

* Targeting

* Bid type

* Bid unit

### Attributes

A/B Tests are represented as nested structures. There are top level fields for the A/B Test itself and an array of user group objects, each with a set of fields describing it.

At a high level, every A/B Test must include the following information.

* The test duration, represented by the start\_time and end\_time fields

* The level at which the split will occur, represented by the entity\_type field

* At least two (and at most 30) user groups, each represented as an object in the user\_groups array

Each user group *must* include the following information.

* The percentage of users that should be allocated to the given user group, represented by the size field

* The campaign IDs/line item IDs that should make up the pool of users for the given user group, represented by the entity\_ids array

Optionally, name and description values can be set for A/B Tests and for user groups. Information about validation rules and other constraints can be found below.

Other metadata, such as the ID or the created at time, are also included, but are automatically set by X.

An example A/B Test entity for campaign level is shown below.

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "created_at": "2020-12-01T00:00:00Z",
  "created_by": {
    "user_id": "756201191646691328",
    "username": "apimctestface"
  },
  "deleted": false,
  "description": "documentation example",
  "end_time": "2020-12-05T01:00:00Z",
  "entity_type": "CAMPAIGN",
  "id": "hr7l0",
  "name": "first AB test",
  "start_time": "2020-12-01T01: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,
      "entity_ids": [
        "f2rqi",
        "f2tws"
      ]
    }
  ],
  "updated_at": "2020-12-01T00:00:00Z",
  "updated_by": {
    "user_id": "756201191646691328",
    "username": "apimctestface"
  }
}
```

An example A/B Test entity for line item level is shown below.

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
   "created_by":{
      "user_id":"756201191646691328",
      "username":"apimctestface"
   },
   "name":"Test2e",
   "start_time":"2022-08-15T00:00:00Z",
   "updated_by":{
      "user_id":"756201191646691328",
      "username":"apimctestface"
   },
   "description":"My Second AB test",
   "entity_type":"LINE_ITEM",
   "end_time":"2022-08-30T00:00:00Z",
   "id":"1ul",
   "user_groups":[
      {
         "name":"first group",
         "size":"50.0",
         "description":"first group description",
         "entity_ids":[
            "ij9dh"
         ],
         "id":"4xe"
      },
      {
         "name":"second group",
         "size":"50.0",
         "description":"second group description",
         "entity_ids":[
            "ihng8"
         ],
         "id":"4xf"
      }
   ],
   "status":"SCHEDULED",
   "created_at":"2022-08-11T00:10:50Z",
   "updated_at":"2022-08-11T00:10:50Z",
   "deleted":false
}
```

### Usage

The subsections below describe creating and updating A/B Tests. Reading and deleting work like they do with all other Ads API endpoints.

#### Creating

Create an A/B Test using the [POST accounts/:account\_id/ab\_tests](https://developer.x.com/en/docs/x-ads-api/measurement/api-reference/ab-tests) endpoint. The endpoint only accepts JSON POST bodies. The Content-Type must be set to application/json.

After the advertiser sets up two or more campaigns, an A/B Test can be created. As stated above, A/B Tests *must* include: test duration, split level, and at least two user groups. Each user group must declare the percentage of users that should be allocated to it as well as the campaign IDs that should make up its pool of users. Each of these is described in further detail below.

Test duration:

* The start\_time and end\_time values must

  * Be in the future (relative to when the A/B Test is created)

  * Overlap with the campaign/line item flight dates

* The test must last at least one day for non-app-based campaigns and last at least five days for app-based campaigns

Split level:

* The entity\_type can be set to CAMPAIGN or LINE\_ITEM

User groups:

* Each user group is represented as an object in the user\_groups array

  * A minimum of two user groups is required

  * A maximum of 30 user groups is allowed

* The size for each user group is set using a string representation of a numeric value between 1.00 and 99.00

  * **Note**: The size values *across objects* **must** add up to 100.00

* The campaign IDs should be specified in each user group's entity\_ids array

Optionally, set the name and description for the A/B Test or for one of more user groups.

The following request creates an A/B Test on the campaign level that lasts four days and has two user groups with 50% of users in each group. The first user group is based on campaigns f2qcw and f2tht; the second user group is based on campaigns f2rqi and f2tws. The request also adds names and descriptions to some parts of the entity.

twurl -X POST -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab\_tests" -d '\{"end\_time": "2020-12-05T01:00:00Z", "entity\_type" : "CAMPAIGN", "start\_time": "2020-12-01T01: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"}'

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
twurl -X POST -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests" -d '{"end_time": "2020-12-05T01:00:00Z", "entity_type" : "CAMPAIGN", "start_time": "2020-12-01T01: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"}'

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "end_time": "2020-12-05T01:00:00Z",
      "entity_type": "CAMPAIGN",
      "start_time": "2020-12-01T01: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": "2020-12-01T00:00:00Z",
    "created_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    },
    "deleted": false,
    "description": "documentation example",
    "end_time": "2020-12-05T01:00:00Z",
    "entity_type": "CAMPAIGN",
    "id": "hr7l0",
    "name": "first AB test",
    "start_time": "2020-12-01T01: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": "2020-12-01T00:00:00Z",
    "updated_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    }
  }
}
```

**For A/B Testing on line item level**

The major difference between A/B testing on the campaign and the line item levels is the entity\_type. We need to set it to ‘entity\_type’ = ‘LINE\_ITEM’ for A/B tests on the line item level. This applies to all the actions on an already created A/B test below. 

Requirements:

1. All line items of the A/B testing campaign must be included in the split test.
2. Only equal splitting is allowed for Line item level.
3. Number of user groups line items allowed in 1 split test must be less than or equal to 5. 
4. Only 1 line item per user group.

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


# Mobile Conversions
Source: https://docs.x.com/x-ads-api/measurement/mobile-conversions

X mobile app promotion measurement allows advertisers to track the success of advertising campaigns on X that are designed to drive installs or other in-app.

## MACT Overview

X [mobile app promotion](https://biz.x.com/mobile-app-promotion) measurement allows advertisers to track the success of advertising campaigns on X that are designed to drive installs or other in-app conversions. A X mobile measurement partner provides the ability for an advertiser to manage what conversions they want to track from the apps they are promoting on X. Once the advertiser has set up the type and time windows of the events they want to track the mobile measurement partner will send all of those events to X and immediately receive attribution data indicating the campaign and creative that the user engaged with to drive the conversion.

### Conversion Events

In order to report a [conversion event](https://developer.x.com/en/docs/x-ads-api/measurement/api-reference/conversion-event) to X and get attribution data the partner must send the mobile app ID, type and timestamp of the conversion, as well as a hashed value of the advertising/device ID. Providing this data will record the conversion event on X’s platform as well as return the attribution where appropriate. In addition, the advertiser may elect to provide extra metadata about the conversion event such as value of a purchase, the ID of a product, or a registration method.

## API reference

### Conversion Event

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### POST conversion\_event

Record a mobile measurement conversion event. The response will indicate X or X Audience Platform (TAP) attribution.

This relates to the [GET conversion\_attribution](https://developer.x.com/en/docs/x-ads-api/measurement/api-reference/conversion-attribution#get-conversion-attribution) 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 (see 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/x-ads-api/measurement/overview/twitter-audience-platform) for more information.

There are several optional parameters available to set metadata associated with each conversion event. This metadata has no effect on attribution calculations.

##### Resource URL

`https://ads-api.x.com/12/conversion_event`

##### Parameters

| Name                                             | Description                                                                                                                                                                                                                                                                                                                                                                         |
| :----------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| app\_id  <br />*required*                        | The unique identifier with the corresponding app store.<br /><br />Type: int, string<br /><br />Example: `333903271`, `com.vine.android`                                                                                                                                                                                                                                            |
| conversion\_time  <br />*required*               | The time of the conversion event in an ISO-8601 timestamp format, with milliseconds appended.<br /><br />Type: string<br /><br />Example: `2014-05-22T02:38:28.103Z`                                                                                                                                                                                                                |
| conversion\_type  <br />*required*               | The type of conversion event.<br /><br />Type: enum<br /><br />Possible values: `PURCHASE`, `SIGN_UP`, `INSTALL`, `RE_ENGAGE`, `UPDATE`, `TUTORIAL_COMPLETE`, `RESERVATION`, `ADD_TO_CART`, `ADD_TO_WISHLIST`, `LOGIN`, `CHECKOUT_INITIATED`, `SEARCH`, `LEVEL_ACHIEVED`, `ACHIEVEMENT_UNLOCKED`, `CONTENT_VIEW`, `SHARE`, `INVITE`, `ADDED_PAYMENT_INFO`, `SPENT_CREDITS`, `RATED` |
| hashed\_device\_id  <br />*required*             | The HMAC\_SHA-256 hashed IDFA or AdID.<br /><br />Type: string<br /><br />Example: `ABCD1234XYZ`                                                                                                                                                                                                                                                                                    |
| os\_type  <br />*required*                       | The OS type for the app.<br /><br />Type: enum<br /><br />Possible values: `IOS`, `ANDROID`                                                                                                                                                                                                                                                                                         |
| click\_window  <br />*optional*                  | The click window for this event in days.<br /><br />Type: int<br /><br />**Note**: `click_window` must be greater than or equal to view\_through\_window<br /><br />Default: `14`  <br />Possible values: `1`, `7`, `14`, `30`                                                                                                                                                      |
| device\_ip\_address  <br />*optional*            | IPv4 or IPv6 address of the device when the conversion event happened.<br /><br />Type: string<br /><br />Example: `192.133.78.1`                                                                                                                                                                                                                                                   |
| level  <br />*optional*                          | A level associated with this event.<br /><br />Type: int<br /><br />Example: `2`                                                                                                                                                                                                                                                                                                    |
| non\_twitter\_engagement\_time  <br />*optional* | The time of the last non-twitter engagement prior to the conversion.<br /><br />Type: string<br /><br />Example: `2014-05-22T02:38:28.103Z`                                                                                                                                                                                                                                         |
| non\_twitter\_engagement\_type  <br />*optional* | The type of non-twitter engagement prior to the conversion event.<br /><br />Type: enum<br /><br />Possible values: `CLICK`, `VIEW`                                                                                                                                                                                                                                                 |
| number\_items  <br />*optional*                  | Number of items associated with this event.<br /><br />Type: int<br /><br />Example: `2`                                                                                                                                                                                                                                                                                            |
| price\_currency  <br />*optional*                | Expected to be an ISO 4217 code to indicate the currency associated with this event.<br /><br />Type: String<br /><br />Examples: `EUR`,`USD`,`JPY`                                                                                                                                                                                                                                 |
| price\_micro  <br />*optional*                   | A price amount associated to this event in micro.<br /><br />Type: int<br /><br />Example: `123450000`                                                                                                                                                                                                                                                                              |
| user\_payment\_info  <br />*optional*            | A boolean value to indicate if the user’s payment information is stored in the app associated with this event.<br /><br />Type: bool<br /><br />Possible values: `true` or `false`                                                                                                                                                                                                  |
| view\_through\_window  <br />*optional*          | The view through window for this event in days.<br /><br />**Note**:<br /><br />`click_window` must be greater than or equal to view\_through\_window.<br /><br />Type: int<br /><br />Default: `1`  <br />Possible values: `0`, `1`, `7`, `14`, `30`                                                                                                                               |

##### Example Request

`https://ads-api.x.com/12/conversion_event?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=1`

##### Example Response

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "data": {
        "conversion_value_micro": 0,
        "view_through_window": 1,
        "tpn_attribution": null,
        "conversion_time": "2017-01-21T01:14:00.602Z",
        "click_window": 30,
        "limit_ad_tracking": false,
        "event_metadata": null,
        "non_twitter_engagement_type": null,
        "conversion_type": "INSTALL",
        "partner_client_id": "com.appname contact id",
        "app_id": "com.appname",
        "hashed_device_id": "lke1GZa3AseB343ZcCQq7svfHzLfuSqyYnE+Rf49MOI=",
        "twitter_attribution": {
          "country_code": "US",
          "engagement_time": "2017-01-21T01:13:00.602Z",
          "engagement_type": "CLICK",
          "attribution_type": "PROMOTED",
          "promoted_properties": {
            "campaign_id": "4ns44",
            "line_item_id": "3x44d",
            "publisher_app_id": "333903271"
            "account_id":"18ce11e3egb",
            "line_item_objective": "APP_INSTALLS",
            "campaign_name": null
          },
          "tweet_id": "11434635565377600"
        },
        "os_type": "ANDROID",
        "non_twitter_engagement_time": null
      },
      "request": {
        "params": {
          "version_number": "1",
          "app_id": "com.appname",
          "conversion_type": "INSTALL",
          "os_type": "ANDROID",
          "hashed_device_id": "lke1GZa3AseB343ZcCQq7svfHzLfuSqyYnE+Rf49MOI=",
          "conversion_time": "2017-01-21T01:14:00.602Z",
          "click_window": "30",
          "view_through_window": "1",
          "limit_ad_tracking": "false"
        }
      }
    }
```

### App Event Tags

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/app\_event\_tags

Retrieve details for some or all app event tags associated with the current account.

These are what define the conversion windows set up per each conversion type for Mobile App Conversion Tracking.

##### Resource URL

`https://ads-api.x.com/12/accounts/:account_id/app_event_tags`

##### Parameters

| Name                                   | Description                                                                                                                                                                                                                                                                                                                                                     |
| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id  <br />*required*          | The identifier 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.<br /><br />Type: string<br /><br />Example: `18ce54d4x5t` |
| app\_event\_tag\_ids  <br />*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.<br /><br />Type: string<br /><br />Example: `jhp`                                                                                                                                                                     |
| count  <br />*optional*                | Specifies the number of records to try and retrieve per distinct request.<br /><br />Type: int<br /><br />Default: `200`  <br />Min, Max: `1`, `1000`                                                                                                                                                                                                           |
| cursor  <br />*optional*               | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.<br /><br />Type: string<br /><br />Example: `8x7v00oow`                                                                                                                                                                                     |
| sort\_by  <br />*optional*             | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.<br /><br />Type: string<br /><br />Example: `created_at-asc`                                                                                                                                                                |
| with\_deleted  <br />*optional*        | Include deleted results in your request.<br /><br />Type: boolean<br /><br />Default: `false`  <br />Possible values: `true`, `false`                                                                                                                                                                                                                           |
| with\_total\_count  <br />*optional*   | Include the `total_count` response attribute.<br /><br />**Note**: This parameter and `cursor` are exclusive.<br /><br />**Note**: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes.<br /><br />Type: boolean<br /><br />Default: `false`  <br />Possible values: `true`, `false`                          |

##### Example Request

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/app_event_tags?app_event_tag_ids=jhp`

##### Example Response

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "app_event_tag_ids": [
            "jhp"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "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
        }
      ]
    }
```

#### GET accounts/:account\_id/app\_event\_tags/:app\_event\_tag\_id

Retrieve a specific app event tag associated with the current account.

These are what define the conversion windows set up per each conversion type for Mobile App Conversion Tracking.

##### Resource URL

`https://ads-api.x.com/12/accounts/:account_id/app_event_tags/:app_event_tag_id`

##### Parameters

| Name                                  | Description                                                                                                                                                                                                                                                                                                                                                     |
| :------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id  <br />*required*         | The identifier 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.<br /><br />Type: string<br /><br />Example: `18ce54d4x5t` |
| app\_event\_tag\_id  <br />*required* | A reference to the app event tag you are operating with in the request.<br /><br />Type: string<br /><br />Example: `jhp`                                                                                                                                                                                                                                       |
| with\_deleted  <br />*optional*       | Include deleted results in your request.<br /><br />Type: boolean<br /><br />Default: `false`  <br />Possible values: `true`, `false`                                                                                                                                                                                                                           |

#### Example Request

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/app_event_tags/jhp`

#### Example Response

```json theme={null}
    {
      "request": {
        "params": {
          "app_event_tag_id": "jhp",
  
```


# Web conversions
Source: https://docs.x.com/x-ads-api/measurement/web-conversions

Set up and use the X Ads API web conversions endpoints to track website conversion events, measure ad performance, and optimize campaign delivery.

## Conversion API Set Up

### Prerequisites 

#### **Ads API Access - New Applications**

* The primary requirement of Conversion API is having a [Developer Account](https://developer.x.com/en/portal/dashboard) and [Ads API Access](https://developer.x.com/en/docs/twitter-ads-api/getting-started). The process is outlined in the [Ads API Getting Started](https://developer.x.com/en/docs/twitter-ads-api/getting-started) guide. Please note the following:

**Step 1: Developer Account**

* When applying for a [Developer Account](https://developer.x.com/en/portal/dashboard), apply for one of our subscription [plans](https://developer.x.com/en/portal/products/) for instant approval. 
* **Note**: As a best practice we highly recommend using your official company X handle to create a developer account and apply to have Ads API access. If the developer account is associated with a developer handle, there is no way to transfer those credentials, if needed. It is best to house under a company account for continual management and utilize [Multi-user login](https://business.x.com/en/help/troubleshooting/multi-user-login-faq.html), as needed. Otherwise at minimum, the account should be set up with non-default settings (header image, avatar, bio description, and bio URL) and use Two-Factor Authentication.

**Step 2: Ads API Application**

* Make sure to have the correct **App** **ID** ready for your Ads API Application. The App ID can be found in the [Developer Console](https://developer.x.com/en/portal/dashboard) under Projects & Apps. Example: 16489123
* Request access to the Ads API using the [Ads API Access Form](/forms/ads-api-access).

#### **Ads API Access - Existing Applications**

* If you already have an actively used Ads API application, both the application and existing access tokens may be used for the Conversion API.

#### **Access Tokens**

* User Access Tokens for the user handle owning the Ads API application can be generated and retrieved directly from the Developer Console. This is called your “personal access token” because it is intended to be used for your own X handle. Overall information about authentication and the Developer Console can be found [here](/resources/fundamentals/authentication/overview).
* 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.
* **Note:** the tokens themselves (after creation per above) can be shared to users without the AD\_MANAGER or ACCOUNT\_ADMIN access level for usage.

### **Steps**

### Creating the Conversion API event

To use the Conversion API, you need to create a new conversion event in Ads Manager or use an existing event already created and used with the X Pixel. If you hope to do deduplication between pixel and conversion API events, you need to use the existing event you created for Pixel. 

##### Option 1: Using an Existing Conversion Event in Ads Manager

If you’d like to use an existing event that you’re already using with the X pixel, that is possible and you’ll need to take the Event ID from that event. If you use both pixel and Conversion API for the same event, ensure to use the deduplication key in both Pixel code snippet and Conversion API request (as `conversion_id`) to deduplicate events between Pixel and Conversion API for the same event. See section d. Testing Events and Deduplication for more information. 

##### Option 2: Creating a New Conversion Event in Ads Manager:

It’s important to have an Event Source created in the Events Manager before you create an event. To verify if you have an Event Source (X Pixel) added to your account, go to Events Manager and see if you have X Pixel on your left menu. 

If you don’t have an Event source added yet, please follow the steps below to create an Event source.

1. Go to ads.x.com
2. Navigate to **Tools** section on the top left and click **Events Manager**
3. Select Add event source on the top right to **Add an event source** if you do not have aad X pixel event source on your left sidebar yet
   1. The ID of X pixel event source is your **Pixel ID**

Now you have an Event source and Pixel ID. You need to create an event inside the event source for the conversion events you hope to track:

1. Inside the X pixel event source, select **Add events** on the right side
2. Select Install with **Conversion API**
3. You will see the **Pixel ID** and **Event ID** of this event that will be used in the API
   1. The ID of the event is your Event ID
4. Click Save and you will have your conversion event created and ready to go

### Preparing Identifiers for Conversion Events 

We currently need at least one identifier to be passed such as Click ID (`twclid`), email address, or phone number. If using IP address or user agent, a second identifier must be sent for proper conversion matching.

Passing more identifiers will yield a higher conversion matching rate.

|                         |                                                                                                                                         |                   |
| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :---------------- |
| Customer matching field | Format                                                                                                                                  | Hashing required? |
| X Click ID              | X generated ([learn more](https://business.x.com/en/help/campaign-measurement-and-analytics/conversion-tracking-for-websites.html#faq)) | No                |
| Email Address           | Remove leading and trailing spaces                                                                                                      | Required (SHA256) |
| Phone Number            | [E164 Standard](https://en.wikipedia.org/wiki/E.164)                                                                                    | Required (SHA256) |

|            |                                    |    |
| :--------- | :--------------------------------- | :- |
| IP Address | Remove leading and trailing spaces | No |
| User Agent | Remove leading and trailing spaces | No |

#### 1. Prepare X Click ID Identifier 

It’s recommended to always include Click ID in the conversion request

The Click ID should be parsed out of the query string parameter twclid when it is available after the user navigates to the destination website. 

Basic JavaScript code example:

```js theme={null}
var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // Recommended next steps: Logging, insert into local storage
}
```

It is recommended to: 

1. Always parse the twclid value when it is present in the URL query parameters.

2. Store the data alongside relevant form fields or conversion event information.

Tying the Click ID to conversion events and workflow information enables scenarios such as batch processing, algorithms to analyze and create conversion events based upon multiple website navigation flows, and bulk uploads.

The Event Source URL should be [URL Encoded](https://en.wikipedia.org/wiki/Percent-encoding) and is meant to represent the web page that triggered the event.

#### 2. Prepare Email Identifier 

Supported customer matching fields may be sent but should be normalized and, when required, hashed to protect privacy.

The information must be hashed using SHA256, without salt. 

For example, for an email address [test@x.com](mailto:test@x.com), it should be sent to us in a hashed format: d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62.

#### 3. Prepare Phone Identifier 

The phone number should be passed in using [E164 Standard](https://en.wikipedia.org/wiki/E.164) and the information must be hashed using SHA256, without salt. 

For example, for a US phone number: +11234567890, it should be sent to us in a hashed format: 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231.

#### 4. Prepare IP Address Identifier

The IP Address is required to be passed in conjunction with another identifier (twclid, email address, phone number or user agent). No hashing is required for this identifier.

This value is written in dotted-decimal notation, with four numbers separated by periods. As an example, a user’s IP Address may be 8.25.197.25.

#### 5. Prepare User Agent Identifier

The User Agent is required to be passed in conjunction with another identifier (twclid, email address, phone number or IP address). No hashing is required for this identifier.

This identifier allows the server to identify the application, operating system, vendor, and/or version of the requesting user agent. For example, this value can be passed as 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.

### Constructing the conversion event request

`POST: version/measurement/conversions/:pixel_id`

Send conversion events for a particular ad account. 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 of error codes are returned.

For detailed information about the endpoint's URL and POST body parameters, please see the [API Reference](https://developer.x.com/en/docs/twitter-ads-api/measurement/api-reference/conversions) section. 

### Example Request (formatted for readability)

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}

    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 Response

```json theme={null}
{"request": {
 "params": {
     "account_id":"18ce552mlaq"}
 },
 "data": {
    "conversions_processed":1,
     "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"}
}
```

### Rate Limit

The rate limit will be 60,000 events per account, per 15 minute interval.

Note that your server code may be required to implement logic outside of this request call, including:

1. Instrumenting user actions (logging) to be able to send correct conversion data per event

2. Any necessary logic to filter out conversion events of users that have exercised relevant privacy choices - for example, if they have opted out of tracking or the sale of their personal information on the advertiser website

3. Integration with event triggers and pages as to capture events and send conversions

### Testing Events and Deduplication

### Test


# Tools and libraries
Source: https://docs.x.com/x-ads-api/tools-and-libraries

Official tools and community client libraries for the X Ads API, including SDKs in multiple languages and helpers for managing campaigns and reports.

## Official tools and libraries

The X teams maintain a small number of SDKs that support the Ads API.

### Python

|                      |                                                                                  |
| :------------------- | :------------------------------------------------------------------------------- |
| **Clients**          | --                                                                               |
| **SDKs / Libraries** | [twitter-python-ads-sdk](https://github.com/xdevplatform/twitter-python-ads-sdk) |
| **Tools**            | --                                                                               |

### Ruby

|                      |                                                                              |
| :------------------- | :--------------------------------------------------------------------------- |
| **Clients**          | --                                                                           |
| **SDKs / Libraries** | [twitter-ruby-ads-sdk](https://github.com/xdevplatform/twitter-ruby-ads-sdk) |
| **Tools**            | --                                                                           |

### Additional resources

**[Postman collection](https://app.getpostman.com/run-collection/369a02c0adc626ff6a06#?env%5BTwitter%20Ads%20API%5D=W3sia2V5IjoiYWNjb3VudF9pZCIsInZhbHVlIjoieW91cl9hZHNfYWNjb3VudF9pZCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidmVyc2lvbiIsInZhbHVlIjoiNiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfa2V5IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX2tleSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfc2VjcmV0IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX3NlY3JldCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYWNjZXNzX3Rva2VuIiwidmFsdWUiOiJ5b3VyX2FjY2Vzc190b2tlbiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidG9rZW5fc2VjcmV0IiwidmFsdWUiOiJ5b3VyX3Rva2VuX3NlY3JldCIsImVuYWJsZWQiOnRydWV9XQ==)**

Explore the Ads API endpoints using Postman, the visual REST client.

***

## Community tools and libraries

These are some of the many community-supported libraries that cover the X Ads API, across several programming languages and platforms. The libraries listed here should support most features of the Ads API, unless otherwise noted - check with the authors for details.

If you have built a library that supports the X APIs, please let us know about it via our [Developer Community forums](https://devcommunity.x.com/c/libraries-and-sdks/63).

### PHP

|                      |                                                                                                                                                                                                               |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Clients**          | --                                                                                                                                                                                                            |
| **SDKs / Libraries** | [twitter-php-ads-sdk](https://github.com/hborras/twitter-php-ads-sdk) by [@hborras](https://github.com/hborras) <br /> [codebird-php](https://github.com/jublo/codebird-php) by [@jublo](https://x.com/jublo) |
| **Tools**            | --                                                                                                                                                                                                            |

### Java

|                      |                                                                                                       |
| :------------------- | :---------------------------------------------------------------------------------------------------- |
| **Clients**          | --                                                                                                    |
| **SDKs / Libraries** | [twitter4j-ads](https://github.com/sprinklr-inc/twitter4j-ads) by [@sprinklr](https://x.com/sprinklr) |
| **Tools**            | --                                                                                                    |

### JavaScript / Node.js

|                      |                                                                                                          |
| :------------------- | :------------------------------------------------------------------------------------------------------- |
| **Clients**          | --                                                                                                       |
| **SDKs / Libraries** | [twitter-ads](https://github.com/FallenTech/twitter-ads) by [@FallenTech](https://github.com/FallenTech) |
| **Tools**            | --                                                                                                       |

### Additional resources

The community tools below can also be useful when working with the X Ads API.

* [**twitter-ads-api-analytics-debugger**](https://github.com/smaeda-ks/twitter-ads-api-analytics-debugger): An Electron-based desktop application for X Ads Analytics API, by [@smaeda-ks](https://github.com/smaeda-ks)


# Create Account Activity replay job
Source: https://docs.x.com/x-api/account-activity/create-replay-job

post /2/account_activity/replay/webhooks/{webhook_id}/subscriptions/all
Create a replay job to redeliver Account Activity API events for an X API v2 webhook subscription over a specified time window of up to five days.

<Warning>
  The Account Activity API (AAA) is being deprecated. Check out the [X Activity API (XAA)](/x-api/activity/introduction) for real-time user activity delivery going forward.
</Warning>


# Create subscription
Source: https://docs.x.com/x-api/account-activity/create-subscription

post /2/account_activity/webhooks/{webhook_id}/subscriptions/all
Creates an Account Activity subscription for the user and the given webhook.



# Delete subscription
Source: https://docs.x.com/x-api/account-activity/delete-subscription

delete /2/account_activity/webhooks/{webhook_id}/subscriptions/{user_id}/all
Deletes an Account Activity subscription for the given webhook and user ID.



# Get Account Activity Subscription Count
Source: https://docs.x.com/x-api/account-activity/get-account-activity-subscription-count

get /2/account_activity/subscriptions/count



# Get Account Activity Subscriptions
Source: https://docs.x.com/x-api/account-activity/get-account-activity-subscriptions

get /2/account_activity/webhooks/{webhook_id}/subscriptions/all/list



# Get Account Activity Subscription Count
Source: https://docs.x.com/x-api/account-activity/get-subscription-count

get /2/account_activity/subscriptions/count



# Get Account Activity Subscriptions
Source: https://docs.x.com/x-api/account-activity/get-subscriptions

get /2/account_activity/webhooks/{webhook_id}/subscriptions/all/list



# Account Activity API v2 introduction and overview
Source: https://docs.x.com/x-api/account-activity/introduction

The Account Activity API (AAA) provides a way to receive real-time events related to X. Reference for the X API v2 standard tier covering account activity.

<Warning>
  The Account Activity API (AAA) is being deprecated. Check out the [X Activity API (XAA)](/x-api/activity/introduction) for real-time user activity delivery going forward.
</Warning>

The Account Activity API (AAA) provides a way to receive real-time events related to X user accounts via webhooks. By subscribing specific user accounts to a pre-configured webhook, your application can be notified of various activities such as Posts, Direct Messages, Likes, Follows, Blocks, and more, from one or more of your owned or subscribed accounts through a single connection.

This API is commonly used to build applications that need to react instantly to user actions or maintain an up-to-date state based on user activity.

## Overview

<CardGroup>
  <Card title="Webhook delivery" icon="webhook">
    Events delivered to your server in real-time
  </Card>

  <Card title="Real-time" icon="bolt">
    Delivers data at the speed of X — no polling required
  </Card>

  <Card title="Comprehensive" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5">
    Posts, DMs, follows, likes, blocks, mutes, and more
  </Card>

  <Card title="Subscription-based" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bell.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=5e0b3dcfbb39ba3d4619931d7cd927d1">
    Subscribe user accounts to receive all their activity
  </Card>
</CardGroup>

***

## How it works

1. **Register webhook** — Register your webhook URL via the [V2 Webhooks API](/x-api/webhooks/introduction)
2. **Subscribe users** — Add user subscriptions to your webhook
3. **Receive events** — Get activity events delivered as POST requests with JSON payloads
4. **Process events** — Handle events in your application and respond with `200 OK`

***

## Activity types

You will receive all related activities below for each user subscription on your webhook registration:

* **Posts** (by user)
* **Post deletes** (by user)
* **@mentions** (of user)
* **Replies** (to or from user)
* **Reposts** (by user or of user)
* **Quote Posts** (by user or of user)
* **Reposts of Quoted Posts** (by user or of user)
* **Likes** (by user or of user)
* **Follows** (by user or of user)
* **Unfollows** (by user or of user)
* **Blocks** (by user or of user)
* **Unblocks** (by user or of user)
* **Mutes** (by user or of user)
* **Unmutes** (by user or of user)
* **Direct Messages sent** (by user)
* **Direct Messages received** (by user)
* **Typing indicators** (to user)
* **Read receipts** (to user)
* **Subscription revokes** (by user)

<Note>
  We do not deliver home timeline data via the Account Activity API. Use the [User Posts timeline by User ID](/x-api/users/get-posts) endpoint to pull this data.

  The returned Posts from the Account Activity API count towards the monthly [Post cap](/x-api/fundamentals/post-cap).
</Note>

***

## Feature summary

| Tier        | Number of Unique Subscriptions | Number of Webhooks |
| :---------- | :----------------------------- | :----------------- |
| Pay Per Use | 3                              | 1                  |
| Enterprise  | 5000+                          | 5+                 |

***

## Account Activity data object structure

| Object          | Details                                                                                                    |
| :-------------- | :--------------------------------------------------------------------------------------------------------- |
| `for_user_id`   | Identifies the user subscription that the event is related to.                                             |
| `is_blocked_by` | (Conditional) Shown only for Post mention events if the mentioning user is blocked by the subscribed user. |
| `source`        | The user performing the activity (e.g., the user following, blocking, or muting).                          |
| `target`        | The user the activity applies to (e.g., the user being followed, blocked, or muted).                       |

### Available activities

| Message Type                            | Details                                                                                        |
| :-------------------------------------- | :--------------------------------------------------------------------------------------------- |
| `tweet_create_events`                   | Post status for Posts, Retweets, Replies, @mentions, Quote Tweets, or Retweet of Quote Tweets. |
| `favorite_events`                       | Like event with user and target.                                                               |
| `follow_events`                         | Follow event with user and target.                                                             |
| `unfollow_events`                       | Unfollow event with user and target.                                                           |
| `block_events`                          | Block event with user and target.                                                              |
| `unblock_events`                        | Unblock event with user and target.                                                            |
| `mute_events`                           | Mute event with user and target.                                                               |
| `unmute_events`                         | Unmute event with user and target.                                                             |
| `user_event`                            | Revoke events when a user removes app authorization (subscription auto-deleted).               |
| `direct_message_events`                 | DM status for sent or received messages.                                                       |
| `direct_message_indicate_typing_events` | DM typing event with user and target.                                                          |
| `direct_message_mark_read_events`       | DM read event with user and target.                                                            |
| `tweet_delete_events`                   | Notice of deleted Posts for compliance.                                                        |

***

## Payload examples

Below are example payloads for each Account Activity event.

### tweet\_create\_events (Posts, Retweets, Replies, QuoteTweets)

```json theme={null}
{
  "for_user_id": "2244994945",
  "tweet_create_events": [
    {
      <Tweet Object>
    }
  ]
}
```

### tweet\_create\_events (@mentions)

```json theme={null}
{
  "for_user_id": "2244994945",
  "user_has_blocked": "false",
  "tweet_create_events": [
    {
      <Tweet Object>
    }
  ]
}
```

### favorite\_events

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "for_user_id": "2244994945",
  "favorite_events": [{
    "id": "a7ba59eab0bfcba386f7acedac279542",
    "created_at": "Mon Mar 26 16:33:26 +0000 2018",
    "timestamp_ms": 1522082006140,
    "favorited_status": {
      <Tweet Object>
    },
    "user": {
      <User Object>
    }
  }]
}
```

### follow\_events

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "for_user_id": "2244994945",
  "follow_events": [{
    "type": "follow",
    "created_timestamp": "1517588749178",
    "target": {
      <User Object>
    },
    "source": {
      <User Object>
    }
  }]
}
```

### unfollow\_events

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "for_user_id": "2244994945",
  "follow_events": [{
    "type": "unfollow",
    "created_timestamp": "1517588749178",
    "target": {
      <User Object>
    },
    "source": {
      <User Object>
    }
  }]
}
```

### block\_events

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "for_user_id": "2244994945",
  "block_events": [{
    "type": "block",
    "created_timestamp": "1518127020304",
    "source": {
      <User Object>
    },
    "target": {
      <User Object>
    }
  }]
}
```

### unblock\_events

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "for_user_id": "2244994945",
  "block_events": [{
    "type": "unblock",
    "created_timestamp": "1518127020304",
    "source": {
      <User Object>
    },
    "target": {
      <User Object>
    }
  }]
}
```

### mute\_events

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "for_user_id": "2244994945",
  "mute_events": [
    {
      "type": "mute",
      "created_timestamp": "1518127020304",
      "source": {
        <User Object>
      },
      "target": {
        <User Object>
      }
    }
  ]
}
```

### unmute\_events

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "for_user_id": "2244994945",
  "mute_events": [
    {
      "type": "unmute",
      "created_timestamp": "1518127020304",
      "source": {
        <User Object>
      },
      "target": {
        <User Object>
      }
    }
  ]
}
```

### user\_event

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "user_event": {
    "revoke": {
      "date_time": "2018-05-24T09:48:12+00:00",
      "target": {
        "app_id": "13090192"
      },
      "source": {
        "user_id": "63046977"
      }
    }
  }
}
```

### direct\_message\_events

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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_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,
      "statuses_count": 240,
      "profile_image_url_https": "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png"
    }
  }
}
```

### direct\_message\_indicate\_typing\_events

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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_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_https": "https://pbs.twimg.com/profile_images/763383202857779200/ndvZ96mE_normal.jpg"
    }
  }
}
```

### direct\_message\_mark\_read\_events

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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_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_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg"
    }
  }
}
```

### tweet\_delete\_events

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "for_user_id": "930524282358325248",
  "tweet_delete_events": [
    {
      "status": {
        "id": "1045405559317569537",
        "user_id": "930524282358325248"
      },
      "timestamp_ms": "1432228155593"
    }
  ]
}
```

***

## Support for longform posts

The V2 Account Activity API supports **longform** posts, which are posts exceeding 280 characters. When a longform post is included in a `tweet_create_events` payload, the `text` field contains the first 140 characters (or fewer), and the `truncated` field is set to `true`. The full post content is delivered in the `extended_tweet` object, which includes:

* `full_text` — The complete text of the post, including all characters beyond the 280-character limit.
* `entities` — Any entities (e.g., hashtags, URLs, user mentions, symbols) appearing in the full text, including those after the 280th character.
* `display_text_range` — The range of characters to display, accounting for the full text.

This ensures that applications can process the entire content of longform posts, including mentions or other entities that appear later in the text. Below is an example of a `tweet_create_events` payload for a longform post:

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "for_user_id": "1603419180975409153",
  "tweet_create_events": [
    {
      "created_at": "Mon May 19 14:01:46 +0000 2025",
      "id": 1924465506158879000,
      "id_str": "1924465506158878979",
      "text": "The Antikythera Mechanism: A Window into Ancient Ingenuity Discovered in 1901 among the wreckage of a Roman ship of… https://t.co/bzbEKj8cd8",
      "display_text_range": [0, 140],
      "truncated": true,
      "user": { ... },
      "extended_tweet": {
        "full_text": "The Antikythera Mechanism: A Window into Ancient Ingenuity Discovered in 1901 among the wreckage of a Roman ship off the Greek island of Antikythera...",
        "display_text_range": [0, 2051],
        "entities": {
          "hashtags": [],
          "urls": [],
          "user_mentions": [
            {
              "screen_name": "xai",
              "name": "xAI",
              "id": 1661523610111193000,
              "id_str": "1661523610111193088",
              "indices": [2032, 2036]
            },
            {
              "screen_name": "HistoryInPics",
              "name": "History Photographed",
              "id": 1582853809,
              "id_str": "1582853809",
              "indices": [2037, 2051]
            }
          ],
          "symbols": []
        }
      },
      "entities": {
        "hashtags": [],
        "urls": [
          {
            "url": "https://t.co/bzbEKj8cd8",
            "expanded_url": "https://twitter.com/i/web/status/1924465506158878979",
            "display_url": "twitter.com/i/web/status/1…",
            "indices": [117, 140]
          }
        ],
        "user_mentions": [],
        "symbols": []
      }
    }
  ]
}
```

***

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What are the advantages of using the Account Activity API?">
    The Account Activity API uses webhooks, delivering data in real-time without requiring an open connection (unlike streaming APIs) or frequent polling (unlike REST APIs). Benefits include:

    * **Speed** — Delivers data at the speed of X.
    * **Simplicity** — Provides all account events through a single webhook connection, including Posts, @mentions, Replies, Reposts, Quote Tweets, Likes, DMs, Follows, Blocks, and Mutes.
    * **Scale** — Supports all activities for managed accounts without rate limits or event caps (Enterprise tier).
  </Accordion>

  <Accordion title="I need development, staging, and production environments. Is this possible?">
    Yes! You can register multiple webhook URLs and manage subscriptions separately via the [V2 Webhooks API](/x-api/webhooks/introduction).
  </Accordion>

  <Accordion title="Do you have any step-by-step guides for getting set up?">
    Yes! See the [Account Activity API Quickstart](/x-api/account-activity/quickstart), the [Getting Started with Webhooks guide](/x-api/webhooks/quickstart), and the [Account Activity API Sample Application](https://github.com/xdevplatform/account-activity-dashboard-enterprise/tree/master).
  </Accordion>

  <Accordion title="What authentication do I need for the Account Activity API?">
    Authentication requirements vary by endpoint:

    * **User-specific actions** (e.g., subscribing a user) require **OAuth 1.0a** (3-legged OAuth flow).
    * **App-level actions** (e.g., listing/deleting subscriptions, subscription count) require **OAuth2 App Only Bearer Token**.

    Review the [Authentication section](/fundamentals/authentication/overview) for details.
  </Accordion>

  <Accordion title="Will I get duplicate activities if subscribed to users interacting with each other?">
    Yes. If your app has subscriptions for User A and User B, and User A mentions User B in a Post, your webhook receives two events (one per user). Use the `for_user_id` field to identify the subscription.
  </Accordion>

  <Accordion title="Can I replace /all/ in the endpoint to limit activities delivered?">
    No. The `/all/` product is the only option, delivering all supported event types.
  </Accordion>

  <Accordion title="If I have access to three webhooks, can I use three webhooks for each of my apps?">
    The webhook limit is set at the account level, not per app. For example, with three webhooks and two apps, you could use two webhooks for one app and one for the other, but not three per app.
  </Accordion>
</AccordionGroup>

***

## API reference index

| Purpose                                           | V2 Endpoint                                                                                                                 |
| :------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------- |
| Subscribes an application to an account's events  | [`POST /2/account_activity/webhooks/:webhook_id/subscriptions/all`](/x-api/account-activity/create-subscription)            |
| Returns a count of currently active subscriptions | [`GET /2/account_activity/subscriptions/count`](/x-api/account-activity/get-subscription-count)                             |
| Checks if a webhook is subscribed to an account   | [`GET /2/account_activity/webhooks/:webhook_id/subscriptions/all`](/x-api/account-activity/validate-subscription)           |
| Returns a list of currently active subscriptions  | [`GET /2/account_activity/webhooks/:webhook_id/subscriptions/all/list`](/x-api/account-activity/get-subscriptions)          |
| Deactivates a subscription using app-only OAuth   | [`DELETE /2/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all`](/x-api/account-activity/delete-subscription) |
| Creates a replay job                              | [`POST /2/account_activity/replay/webhooks/:webhook_id/subscriptions/all`](/x-api/account-activity/create-replay-job)       |

For webhook management endpoints (register, view, validate, delete), see the [V2 Webhooks API documentation](/x-api/webhooks/introduction).

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * A publicly accessible HTTPS webhook endpoint
  * Enterprise or Pay Per Use access for the Account Activity API
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/account-activity/quickstart">
    Set up subscriptions and start receiving events
  </Card>

  <Card title="Webhooks API" icon="webhook" href="/x-api/webhooks/introduction">
    Register and manage your webhooks
  </Card>

  <Card title="Migration guide" icon="right-left" href="/x-api/account-activity/migrate/overview">
    Migrate from legacy Enterprise to v2
  </Card>

  <Card title="Activity stream" icon="bars-staggered" href="/x-api/activity/introduction">
    Streaming alternative to webhooks
  </Card>
</CardGroup>


# Account Activity API v2 migration guide
Source: https://docs.x.com/x-api/account-activity/migrate/overview

Step-by-step guide to migrate webhooks, subscriptions, and authentication from the legacy Account Activity API to the X API v2 equivalents.

<Warning>
  The Account Activity API (AAA) is being deprecated. Check out the [X Activity API (XAA)](/x-api/activity/introduction) for real-time user activity delivery going forward.
</Warning>

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.

### Summary of Changes

* **API Format**: Endpoints use the /2/account\_activity/ base path instead of /1.1/account\_activity/.
* **Webhook Management**: Webhook creation, listing, validation (CRC), and deletion are handled by the [V2 Webhooks API](https://github.com/m-rosinsky/XWebhookTest/blob/main/app.py).
* **Authentication**: V2 endpoints require either:
  * **OAuthUser** (3-legged OAuth) for user-specific actions (e.g., subscribing a user).
  * **OAuth2 App Only** (Bearer Token) for app-level actions (e.g., listing/deleting subscriptions).
  * V1.1 used varying requirements, often OAuth 1.0a.
* **Endpoint Mapping**:

| V1.1 Endpoint                                                                   | V2 Equivalent / Action                                                        | Notes                                                                                         |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| POST /1.1/account\_activity/webhooks.json?url=\<URL>                            | POST /2/webhooks                                                              | [Docs](https://docs.x.com/x-api/webhooks/introduction). Requires OAuth2AppOnly.               |
| GET /1.1/account\_activity/webhooks.json                                        | GET /2/webhooks                                                               | [Docs](https://docs.x.com/x-api/webhooks/introduction). Requires OAuth2AppOnly.               |
| PUT /1.1/account\_activity/webhooks/:webhook\_id.json                           | PUT /2/webhooks/:webhook\_id                                                  | Triggers CRC. [Docs](https://docs.x.com/x-api/webhooks/introduction). Requires OAuth2AppOnly. |
| DELETE /1.1/account\_activity/webhooks/:webhook\_id.json                        | DELETE /2/webhooks/:webhook\_id                                               | [Docs](https://docs.x.com/x-api/webhooks/introduction). Requires OAuth2AppOnly.               |
| POST /1.1/account\_activity/webhooks/:webhook\_id/subscriptions/all.json        | POST /2/account\_activity/webhooks/:webhook\_id/subscriptions/all             | Requires OAuthUser.                                                                           |
| GET /1.1/account\_activity/subscriptions/count.json                             | GET /2/account\_activity/subscriptions/count                                  | Requires OAuth2AppOnly.                                                                       |
| GET /1.1/account\_activity/webhooks/:webhook\_id/subscriptions/all.json         | GET /2/account\_activity/webhooks/:webhook\_id/subscriptions/all              | Requires OAuthUser.                                                                           |
| GET /1.1/account\_activity/webhooks/:webhook\_id/subscriptions/all/list.json    | GET /2/account\_activity/webhooks/:webhook\_id/subscriptions/all/list         | Requires OAuth2AppOnly.                                                                       |
| DELETE /1.1/account\_activity/webhooks/:webhook\_id/subscriptions/:user\_id/all | DELETE /2/account\_activity/webhooks/:webhook\_id/subscriptions/:user\_id/all | Requires OAuth2AppOnly.                                                                       |
| DELETE /1.1/account\_activity/webhooks/:webhook\_id/subscriptions/all           | Deprecated / No Direct Equivalent                                             | Use individual deletes or remove the webhook via DELETE /2/webhooks/:webhook\_id.             |

* **Response Formats**: Review the success and error response structures in the AAAPI documentation.

When migrating, update your code to use the new base paths, adjust authentication flows, and manage webhooks using the [V2 Webhooks API](https://docs.x.com/x-api/webhooks/introduction).

### How to Migrate

* **Decide on a Package**:
  * Choose the Enterprise or Self-serve package for Account Activity API access, considering:
    * Number of webhooks needed.
    * Current/projected subscriptions or authorized users.
    * Number of X client applications.
    * Desired support level (forum vs. managed enterprise 1:1 support).
    * Pricing details (contact sales for Enterprise).
* **Update Your Authentication to OAuth 2.0**:
  * Ensure your X App has “Read, Write, and Access Direct Messages” permissions.
  * Update to OAuth 2.0 for V2 endpoints. Re-authorize users if scopes have changed.
  * Use the Developer Console to manage:
    * OAuth 2.0 Access Token.
    * Client ID and Client Secret.
* **Verify or Reconfigure Your Webhook**:
  * Use your existing webhook URL or set up a new one (e.g., [https://your\\\_domain.com/webhook/twitter](https://your\\_domain.com/webhook/twitter)).
  * Follow the [V2 Webhooks API documentation](https://docs.x.com/x-api/webhooks/introduction) to register and manage your webhook.
* **Sample Apps:**
  * [Simple webhook server](https://github.com/m-rosinsky/XWebhookTest/blob/main/app.py)
    * A single python script that shows you how to respond to the CRC check and accept POST events.
  * [Account Activity API sample dashboard](https://github.com/xdevplatform/account-activity-dashboard-enterprise/tree/master)
    * A web app written with [bun.sh](http://bun.sh) that allows you to manage webhooks, subscriptions, and receive live events directly in the app.


# Account Activity API quickstart guide
Source: https://docs.x.com/x-api/account-activity/quickstart

Set up the Account Activity API, register a webhook, manage user subscriptions, and start receiving real-time X account events in this quickstart.

<Warning>
  The Account Activity API (AAA) is being deprecated. Check out the [X Activity API (XAA)](/x-api/activity/introduction) for real-time user activity delivery going forward.
</Warning>

This guide walks you through setting up the Account Activity API, managing user subscriptions, validating your webhook, and using the replay feature to recover missed events.

## 1. Create an X App

Create an X app with an approved developer account from the [developer portal](https://developer.x.com/en/portal/products/enterprise). If creating the app on behalf of your company, use a corporate X account.

* Enable **"Read, Write, and Access direct messages"** on the permissions tab of your app page.
* On the "Keys and Access Tokens" tab, note your app's **Consumer Key (API Key)**, **Consumer Token (API Secret)**, and **Bearer Token**.
* Generate your app's **Access Token** and **Access Token Secret**. These are needed to subscribe to user accounts.
* Review [Obtaining Access Tokens](/fundamentals/authentication/overview) if unfamiliar with X Sign-in and user contexts.
* Note your app's numeric ID from the "Apps" page in the developer portal. This is required when applying for Account Activity API access.

***

## 2. Get Account Activity API access

The Account Activity API is available on the Enterprise and Pay Per Use tiers. Submit an application for access via the [developer portal](https://developer.x.com/en/portal/products/enterprise).

***

## 3. Register a webhook

To receive Account Activity events, you must register a webhook with a publicly accessible HTTPS URL. See the [V2 Webhooks API documentation](/x-api/webhooks/introduction) for details on developing a webhook consumer app, registering a webhook, securing it, and handling Challenge-Response Checks (CRC).

* Ensure your webhook is configured to handle POST requests with JSON-encoded event payloads.
* Obtain the **`webhook_id`** from the webhook registration response, as it is required for managing subscriptions.

```bash theme={null}
curl --request POST \
  --url 'https://api.x.com/2/webhooks' \
  --header 'Authorization: Bearer $BEARER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://yourdomain.com/webhooks/twitter"}'
```

***

## 4. Validate setup

To validate that your app and webhook are configured correctly:

1. Subscribe a user account to your webhook (see [Adding a Subscription](#adding-a-subscription) below).
2. Favorite a Post posted by one of the X accounts your app is subscribed to.
3. You should receive a `favorite_events` payload via a POST request to your webhook URL.

<Note>
  It may take up to 10 seconds for events to start being delivered after adding a subscription.
</Note>

***

## Managing subscriptions

Once you have a registered webhook with a valid `webhook_id`, you can manage user subscriptions to receive their account activities. Use the following endpoints to add, view, or remove subscriptions.

### Adding a subscription

**Endpoint:** `POST /2/account_activity/webhooks/:webhook_id/subscriptions/all` — [API Reference](/x-api/account-activity/create-subscription)

Subscribes the authenticating user to receive events via the specified webhook.

**Authentication:** OAuth 1.0a (3-legged OAuth flow required, representing the user being subscribed).

| Path Parameter | Description                                               |
| :------------- | :-------------------------------------------------------- |
| `webhook_id`   | The ID of the webhook to associate the subscription with. |

```bash theme={null}
curl --request POST \
  --url 'https://api.x.com/2/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all' \
  --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"'
```

**Success (200 OK):**

```json theme={null}
{
  "data": {
    "subscribed": true
  }
}
```

**Failure reasons:**

| Reason                        | Description                                                                 |
| :---------------------------- | :-------------------------------------------------------------------------- |
| `WebhookIdInvalid`            | The provided `webhook_id` was not found or is not associated with the app.  |
| `DuplicateSubscriptionFailed` | A subscription for this user already exists for the specified `webhook_id`. |
| `SubscriptionLimitExceeded`   | The application has reached its subscription limit across all webhooks.     |

***

### Checking a subscription

**Endpoint:** `GET /2/account_activity/webhooks/:webhook_id/subscriptions/all` — [API Reference](/x-api/account-activity/validate-subscription)

Checks if the authenticating user is subscribed to the specified webhook.

**Authentication:** OAuth 1.0a (3-legged OAuth flow required).

| Path Parameter | Description                     |
| :------------- | :------------------------------ |
| `webhook_id`   | The ID of the webhook to check. |

```bash theme={null}
curl --request GET \
  --url 'https://api.x.com/2/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all' \
  --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"'
```

**Success (200 OK):**

```json theme={null}
{
  "data": {
    "subscribed": true
  }
}
```

**Failure reasons:**

| Reason             | Description                                                                |
| :----------------- | :------------------------------------------------------------------------- |
| `WebhookIdInvalid` | The provided `webhook_id` was not found or is not associated with the app. |

***

### Removing a subscription

**Endpoint:** `DELETE /2/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all` — [API Reference](/x-api/account-activity/delete-subscription)

Deactivates the subscription for a specific user ID, stopping event delivery to the webhook.

**Authentication:** OAuth2 App Only Bearer Token.

| Path Parameter | Description                                        |
| :------------- | :------------------------------------------------- |
| `webhook_id`   | The ID of the webhook containing the subscription. |
| `user_id`      | The numerical ID of the user to unsubscribe.       |

```bash theme={null}
curl --request DELETE \
  --url 'https://api.x.com/2/account_activity/webhooks/:WEBHOOK_ID/subscriptions/:USER_ID/all' \
  --header 'authorization: Bearer <BEARER_TOKEN>'
```

**Success (200 OK):**

```json theme={null}
{
  "data": {
    "subscribed": false
  }
}
```

**Failure reasons:**

| Reason                 | Description                                                                   |
| :--------------------- | :---------------------------------------------------------------------------- |
| `SubscriptionNotFound` | No subscription exists for the specified `user_id` on the given `webhook_id`. |
| `WebhookIdInvalid`     | The provided `webhook_id` was not found or is not associated with the app.    |

***

### Viewing all subscriptions

**Endpoint:** `GET /2/account_activity/webhooks/:webhook_id/subscriptions/all/list` — [API Reference](/x-api/account-activity/get-subscriptions)

Retrieves a list of all user IDs currently subscribed to the specified webhook.

**Authentication:** OAuth2 App Only Bearer Token.

| Path Parameter | Description                                      |
| :------------- | :----------------------------------------------- |
| `webhook_id`   | The ID of the webhook to list subscriptions for. |

```bash theme={null}
curl --request GET \
  --url 'https://api.x.com/2/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all/list' \
  --header 'authorization: Bearer <BEARER_TOKEN>'
```

**Success (200 OK):**

```json theme={null}
{
  "data": {
    "application_id": "<your app id>",
    "webhook_id": "<webhook id>",
    "webhook_url": "<the webhook's callback url>",
    "subscriptions": [
      { "user_id": "<user_id_1>" },
      { "user_id": "<user_id_2>" }
    ]
  }
}
```

**Failure reasons:**

| Reason             | Description                                                                |
| :----------------- | :------------------------------------------------------------------------- |
| `WebhookIdInvalid` | The provided `webhook_id` was not found or is not associated with the app. |

***

### Subscription count

**Endpoint:** `GET /2/account_activity/subscriptions/count` — [API Reference](/x-api/account-activity/get-subscription-count)

Returns the total count of active subscriptions and the provisioned limit for the authenticating application.

**Authentication:** OAuth2 App Only Bearer Token.

```bash theme={null}
curl --request GET \
  --url 'https://api.x.com/2/account_activity/subscriptions/count' \
  --header 'authorization: Bearer <BEARER_TOKEN>'
```

**Success (200 OK):**

```json theme={null}
{
  "data": {
    "account_name": "<your application name>",
    "provisioned_count": "<subscription limit allocated>",
    "subscriptions_count_all": "<current active subscription count>",
    "subscriptions_count_direct_messages": "0"
  }
}
```

<Note>
  DM-only subscriptions are no longer supported. The `subscriptions_count_direct_messages` field will always be `"0"`.
</Note>

***

## Replay

AAAv2 provides replay functionality that allows you to retrieve past events for a specified time range and re-deliver them to your webhook. This is useful for recovering missed events due to downtime.

**Endpoint:** `POST /2/account_activity/replay/webhooks/:webhook_id/subscriptions/all` — [API Reference](/x-api/account-activity/create-replay-job)

**Authentication:** OAuth2 App Only Bearer Token.

| Path Parameter | Description                            |
| :------------- | :------------------------------------- |
| `webhook_id`   | The ID of the webhook to begin replay. |

| Query Parameter | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
| :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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 24 hours, UTC time, and no more recent than 31 minutes before the current point in time. It's recommended that `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 24 hours, UTC time, and no more than 10 minutes before the current point in time.                                                                   |

**Success (200 OK):**

```json theme={null}
{
  "for_user_id": "<USER_ID>",
  "replay_event": {
    "job_id": "<REPLAY_JOB_ID>",
    "created_at": "yyyy-mm-ddThh:mm:ss.000Z"
  }
}
```

**Failure reasons:**

| Reason                | Description                                                             |
| :-------------------- | :---------------------------------------------------------------------- |
| `QueryParamInvalid`   | `from_date` is older than 24 hours from the current time.               |
| `QueryParamInvalid`   | `from_date` is more recent than `to_date`.                              |
| `QueryParamInvalid`   | `from_date` is in the future.                                           |
| `QueryParamInvalid`   | `to_date` is in the future.                                             |
| `QueryParamInvalid`   | `from_date` or `to_date` is not in the correct format.                  |
| `CrcValidationFailed` | Incorrect response received from the webhook URL during CRC validation. |
| `ReplayConflictError` | A replay job is already in progress for the specified webhook.          |
| `WebhookIdInvalid`    | The provided `webhook_id` is invalid or not associated with the app.    |

### Job completed messages

Once your replay job successfully completes, X will deliver the following job completion event. Once you receive this event, the job has finished running and another can be submitted.

```json theme={null}
{
  "replay_job_status": {
    "webhook_id": "<WEBHOOK_ID>",
    "job_state": "Complete",
    "job_state_description": "Job completed successfully",
    "job_id": "<JOB_ID>"
  }
}
```

In the event your job does not complete successfully, X 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 theme={null}
{
  "replay_job_status": {
    "webhook_id": "<WEBHOOK_ID>",
    "job_state": "Incomplete",
    "job_state_description": "Job failed to deliver all events, please retry your replay job",
    "job_id": "<JOB_ID>"
  }
}
```

***

## Important notes

<Warning>
  * **Authentication**: When subscribing users, use the consumer key, consumer secret, access token, and access token secret for the user's account.
  * **Direct Messages**: All incoming and outgoing Direct Messages (sent via `POST /2/dm_conversations/with/:participant_id/messages`) are delivered via webhooks to keep your app aware of all DM activity.
  * **Event Duplication**:
    * If two subscribed users are in the same DM conversation, your webhook receives duplicate events (one per user). Use the `for_user_id` field to distinguish them.
    * If multiple apps share the same webhook URL and user, events are sent multiple times (once per app).
    * Your app should deduplicate events using the event ID to handle occasional duplicates.
</Warning>

***

## Sample apps

| App                                                                                                                 | Description                                                                                                           |
| :------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------- |
| [Simple webhook server](https://github.com/m-rosinsky/XWebhookTest/blob/main/app.py)                                | A single Python script that shows how to respond to the CRC check and accept POST events                              |
| [Account Activity API dashboard](https://github.com/xdevplatform/account-activity-dashboard-enterprise/tree/master) | A web app written with [bun.sh](https://bun.sh) that lets you manage webhooks, subscriptions, and receive live events |

***

## Next steps

<CardGroup>
  <Card title="Introduction" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/account-activity/introduction">
    Activity types, data objects, and payload examples
  </Card>

  <Card title="Webhooks API" icon="webhook" href="/x-api/webhooks/introduction">
    Register and manage your webhooks
  </Card>

  <Card title="Migration guide" icon="right-left" href="/x-api/account-activity/migrate/overview">
    Migrate from legacy Enterprise to v2
  </Card>

  <Card title="Webhook quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/webhooks/quickstart">
    CRC setup, security, and webhook registration
  </Card>
</CardGroup>


# Validate Account Activity Subscription
Source: https://docs.x.com/x-api/account-activity/validate-account-activity-subscription

get /2/account_activity/webhooks/{webhook_id}/subscriptions/all



# Validate Account Activity Subscription
Source: https://docs.x.com/x-api/account-activity/validate-subscription

get /2/account_activity/webhooks/{webhook_id}/subscriptions/all



# Activity Stream
Source: https://docs.x.com/x-api/activity/activity-stream

get /2/activity/stream
Stream of X Activities



# Create X activity subscription
Source: https://docs.x.com/x-api/activity/create-x-activity-subscription

post /2/activity/subscriptions
Creates a subscription for an X activity event. OAuth2 user-context tokens must hold the scope matching the requested event_type: dm.read for chat.* and dm.* events, like.read for like.* events, mute.read for mute.* events, block.read for block.* events, and tweet.read for all other event types. Mute and block subscriptions are actor-only: filter.user_id must identify the authenticated user and direction is not supported.



# Delete X activity subscriptions by IDs
Source: https://docs.x.com/x-api/activity/delete-x-activity-subscriptions-by-ids

delete /2/activity/subscriptions
Deletes multiple subscriptions for X activity events by their IDs



# Deletes X activity subscription
Source: https://docs.x.com/x-api/activity/deletes-x-activity-subscription

delete /2/activity/subscriptions/{subscription_id}
Deletes a subscription for an X activity event



# X Activity API event payload examples
Source: https://docs.x.com/x-api/activity/event-payloads

Sample JSON payloads for X Activity API events, including posts, likes, follows, profile updates, chat, DMs, mutes, blocks, Spaces, news, and OAuth revokes.

Events delivered by the X Activity API (via the [persistent HTTP stream](/x-api/activity/activity-stream) or [webhooks](/x-api/webhooks/introduction)) share a common envelope:

| Field        | Description                                                         |
| ------------ | ------------------------------------------------------------------- |
| `event_uuid` | Unique identifier for this event delivery                           |
| `filter`     | The filter that matched (for example `user_id` or `keyword`)        |
| `event_type` | The subscribed event type                                           |
| `tag`        | Optional tag from your subscription (when set)                      |
| `payload`    | Event-specific data                                                 |
| `includes`   | Optional expanded objects (users, tweets, and so on) when available |

```json title="Event envelope" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "2080761390344937796",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "post.create",
    "tag": "posts",
    "payload": {},
    "includes": {}
  }
}
```

The examples below are representative real-world payloads with sample account identifiers and profile fields substituted for documentation. Field availability can vary based on account settings, expansions, and the object state at delivery time. See the [introduction](/x-api/activity/introduction) for the full list of supported event types and authentication requirements.

Payload samples use Mintlify code blocks with titles, line numbers, and wrapping. Longer examples are expandable—click to expand and copy the full delivery body.

***

## Post events

### `post.create`

Fired when the filtered user creates a Post. Fires for standalone Posts, replies, quote Posts, and reposts by the filtered user. Inspect the payload to distinguish the type — for example, `in_reply_to_tweet_id` is present on replies, and `referenced_tweets` indicates quotes and reposts. The `payload` is a Post object; `includes` may contain related users and tweets.

```json title="post.create" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "2080761390344937796",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "post.create",
    "tag": "posts",
    "payload": {
      "public_metrics": {
        "retweet_count": 0,
        "retweet_count_str": "0",
        "reply_count": 0,
        "reply_count_str": "0",
        "like_count": 0,
        "like_count_str": "0",
        "quote_count": 0,
        "quote_count_str": "0",
        "bookmark_count": 0,
        "bookmark_count_str": "0",
        "impression_count": 0,
        "impression_count_str": "0"
      },
      "lang": "en",
      "created_at": "2026-07-24T21:05:48.000Z",
      "author_id": "1111111111111111111",
      "reply_settings": "everyone",
      "display_text_range": [
        0,
        34
      ],
      "paid_partnership": false,
      "id": "2080761390344937796",
      "possibly_sensitive": false,
      "edit_history_tweet_ids": [
        "2080761390344937796"
      ],
      "conversation_id": "2080761390344937796",
      "text": "Hello from the Activity API",
      "edit_controls": {
        "edits_remaining": 5,
        "edits_remaining_str": "5",
        "is_edit_eligible": true,
        "editable_until": "2026-07-24T22:05:48.000Z"
      }
    },
    "includes": {
      "tweets": [
        {
          "public_metrics": {
            "retweet_count": 0,
            "retweet_count_str": "0",
            "reply_count": 0,
            "reply_count_str": "0",
            "like_count": 0,
            "like_count_str": "0",
            "quote_count": 0,
            "quote_count_str": "0",
            "bookmark_count": 0,
            "bookmark_count_str": "0",
            "impression_count": 0,
            "impression_count_str": "0"
          },
          "lang": "en",
          "created_at": "2026-07-24T21:05:48.000Z",
          "author_id": "1111111111111111111",
          "reply_settings": "everyone",
          "display_text_range": [
            0,
            34
          ],
          "paid_partnership": false,
          "id": "2080761390344937796",
          "possibly_sensitive": false,
          "edit_history_tweet_ids": [
            "2080761390344937796"
          ],
          "conversation_id": "2080761390344937796",
          "text": "Hello from the Activity API",
          "edit_controls": {
            "edits_remaining": 5,
            "edits_remaining_str": "5",
            "is_edit_eligible": true,
            "editable_until": "2026-07-24T22:05:48.000Z"
          }
        }
      ],
      "users": [
        {
          "entities": {
            "url": {
              "urls": [
                {
                  "start": 0,
                  "start_str": "0",
                  "end": 23,
                  "end_str": "23",
                  "url": "https://t.co/xxxxxxxx",
                  "expanded_url": "https://example.com",
                  "display_url": "https://example.com"
                }
              ]
            },
            "description": {
              "mentions": [
                {
                  "start": 49,
                  "start_str": "49",
                  "end": 51,
                  "end_str": "51",
                  "username": "X"
                },
                {
                  "start": 52,
                  "start_str": "52",
                  "end": 64,
                  "end_str": "64",
                  "username": "XDevelopers"
                }
              ]
            }
          },
          "name": "Example User",
          "protected": false,
          "verified": true,
          "description": "Building with the X AnotherUser @XDevelopers",
          "is_identity_verified": true,
          "affiliation": {
            "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
            "url": "https://twitter.com/X",
            "user_id": [
              "783214"
            ],
            "description": "X"
          },
          "location": "San Francisco, CA",
          "username": "ExampleUser",
          "verified_type": "blue",
          "pinned_tweet_id": "1968451310203859083",
          "created_at": "2023-10-23T13:44:53.000Z",
          "id": "1111111111111111111",
          "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
          "url": "https://t.co/xxxxxxxx",
          "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
          "most_recent_tweet_id": "2080761390344937796",
          "public_metrics": {
            "followers_count": 5502,
            "followers_count_str": "5502",
            "following_count": 652,
            "following_count_str": "652",
            "tweet_count": 790,
            "tweet_count_str": "790",
            "listed_count": 47,
            "listed_count_str": "47",
            "like_count": 8011,
            "like_count_str": "8011",
            "media_count": 79,
            "media_count_str": "79"
          },
          "profile_geo_enrichment": {
            "potential_locations": [
              {
                "geo_entity": {
                  "entity_id": "5391959",
                  "display_name": "San Francisco, California, United States",
                  "country_code": "US",
                  "region": "California",
                  "sub_region": "San Francisco County",
                  "locality": "San Francisco",
                  "population": 873965,
                  "population_str": "873965",
                  "geo_point": {
                    "latitude": 37.77493,
                    "longitude": -122.41942
                  }
                }
              }
            ]
          }
        }
      ]
    }
  }
}
```

### `post.delete`

Fired when the filtered user deletes a Post. The `payload` contains the deleted Post ID and author ID.

```json title="post.delete" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "-2781149976877970683",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "post.delete",
    "tag": "post-deletes",
    "payload": {
      "id": "2080761269309813134",
      "author_id": "1111111111111111111"
    },
    "includes": {
      "users": [
        {
          "data": {
            "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
            "affiliation": {
              "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
              "url": "https://twitter.com/X",
              "description": "X"
            },
            "protected": false,
            "id": "1111111111111111111",
            "username": "ExampleUser",
            "verified_type": "blue",
            "verified": true,
            "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
            "entities": {
              "url": {
                "urls": [
                  {
                    "start": 0,
                    "start_str": "0",
                    "end": 23,
                    "end_str": "23",
                    "url": "https://t.co/xxxxxxxx",
                    "expanded_url": "https://example.com",
                    "display_url": "https://example.com"
                  }
                ]
              },
              "description": {
                "mentions": [
                  {
                    "start": 49,
                    "start_str": "49",
                    "end": 51,
                    "end_str": "51",
                    "username": "X"
                  },
                  {
                    "start": 52,
                    "start_str": "52",
                    "end": 64,
                    "end_str": "64",
                    "username": "XDevelopers"
                  }
                ]
              }
            },
            "public_metrics": {
              "followers_count": 5502,
              "followers_count_str": "5502",
              "following_count": 651,
              "following_count_str": "651",
              "tweet_count": 789,
              "tweet_count_str": "789",
              "listed_count": 47,
              "listed_count_str": "47",
              "like_count": 8010,
              "like_count_str": "8010",
              "media_count": 79,
              "media_count_str": "79"
            },
            "url": "https://t.co/xxxxxxxx",
            "created_at": "2023-10-23T13:44:53.000Z",
            "description": "Building with the X AnotherUser @XDevelopers",
            "is_identity_verified": true,
            "location": "San Francisco, CA",
            "name": "Example User"
          }
        }
      ]
    }
  }
}
```

### `post.mention.create`

Fired when another user explicitly @mentions the filtered user in the body of a Post. Does not fire for implicit mentions carried by replies or reposts. Private event — requires user-context authentication with the `tweet.read` scope.

```json title="post.mention.create" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "2080765813578191303",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "post.mention.create",
    "tag": "mentions",
    "payload": {
      "paid_partnership": false,
      "created_at": "2026-07-24T21:23:23.000Z",
      "edit_history_tweet_ids": [
        "2080765813578191303"
      ],
      "conversation_id": "2080765813578191303",
      "display_text_range": [
        0,
        16
      ],
      "edit_controls": {
        "edits_remaining": 5,
        "edits_remaining_str": "5",
        "is_edit_eligible": true,
        "editable_until": "2026-07-24T22:23:23.000Z"
      },
      "text": "hey @ExampleUser",
      "entities": {
        "mentions": [
          {
            "start": 4,
            "start_str": "4",
            "end": 16,
            "end_str": "16",
            "username": "ExampleUser",
            "id": "1111111111111111111"
          }
        ]
      },
      "author_id": "2222222222222222222",
      "possibly_sensitive": false,
      "public_metrics": {
        "retweet_count": 0,
        "retweet_count_str": "0",
        "reply_count": 0,
        "reply_count_str": "0",
        "like_count": 0,
        "like_count_str": "0",
        "quote_count": 0,
        "quote_count_str": "0",
        "bookmark_count": 0,
        "bookmark_count_str": "0",
        "impression_count": 0,
        "impression_count_str": "0"
      },
      "reply_settings": "everyone",
      "id": "2080765813578191303",
      "lang": "und"
    },
    "includes": {
      "users": [
        {
          "public_metrics": {
            "followers_count": 97,
            "followers_count_str": "97",
            "following_count": 1,
            "following_count_str": "1",
            "tweet_count": 50,
            "tweet_count_str": "50",
            "listed_count": 4,
            "listed_count_str": "4",
            "like_count": 26,
            "like_count_str": "26",
            "media_count": 3,
            "media_count_str": "3"
          },
          "profile_banner_url": "",
          "username": "OtherUser",
          "protected": false,
          "is_identity_verified": false,
          "affiliation": {
            "badge_url": "https://pbs.twimg.com/semantic_core_img/1428827730364096519/4ZXpTBhS?format=png&name=orig",
            "description": "Automated"
          },
          "most_recent_tweet_id": "2080765813578191303",
          "verified_type": "none",
          "description": "",
          "created_at": "2026-04-20T19:55:59.000Z",
          "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
          "name": "OtherUser",
          "verified": false,
          "url": "",
          "id": "2222222222222222222"
        },
        {
          "public_metrics": {
            "followers_count": 5502,
            "followers_count_str": "5502",
            "following_count": 651,
            "following_count_str": "651",
            "tweet_count": 789,
            "tweet_count_str": "789",
            "listed_count": 46,
            "listed_count_str": "46",
            "like_count": 8010,
            "like_count_str": "8010",
            "media_count": 79,
            "media_count_str": "79"
          },
          "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
          "username": "ExampleUser",
          "protected": false,
          "is_identity_verified": true,
          "affiliation": {
            "user_id": [
              "783214"
            ],
            "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
            "url": "https://twitter.com/X",
            "description": "X"
          },
          "most_recent_tweet_id": "2080761269309813134",
          "verified_type": "blue",
          "description": "Building with the X AnotherUser @XDevelopers",
          "pinned_tweet_id": "1968451310203859083",
          "created_at": "2023-10-23T13:44:53.000Z",
          "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
          "name": "Example User",
          "verified": true,
          "url": "https://t.co/xxxxxxxx",
          "location": "San Francisco, CA",
          "id": "1111111111111111111",
          "entities": {
            "url": {
              "urls": [
                {
                  "start": 0,
                  "start_str": "0",
                  "end": 23,
                  "end_str": "23",
                  "url": "https://t.co/xxxxxxxx",
                  "expanded_url": "https://developer.x.com",
                  "display_url": "developer.x.com"
                }
              ]
            },
            "description": {
              "mentions": [
                {
                  "start": 48,
                  "start_str": "48",
                  "end": 50,
                  "end_str": "50",
                  "username": "X"
                },
                {
                  "start": 51,
                  "start_str": "51",
                  "end": 63,
                  "end_str": "63",
                  "username": "XDevelopers"
                }
              ]
            }
          }
        }
      ],
      "tweets": [
        {
          "paid_partnership": false,
          "created_at": "2026-07-24T21:23:23.000Z",
          "edit_history_tweet_ids": [
            "2080765813578191303"
          ],
          "conversation_id": "2080765813578191303",
          "display_text_range": [
            0,
            16
          ],
          "edit_controls": {
            "edits_remaining": 5,
            "edits_remaining_str": "5",
            "is_edit_eligible": true,
            "editable_until": "2026-07-24T22:23:23.000Z"
          },
          "text": "hey @ExampleUser",
          "entities": {
            "mentions": [
              {
                "start": 4,
                "start_str": "4",
                "end": 16,
                "end_str": "16",
                "username": "ExampleUser",
                "id": "1111111111111111111"
              }
            ]
          },
          "author_id": "2222222222222222222",
          "possibly_sensitive": false,
          "public_metrics": {
            "retweet_count": 0,
            "retweet_count_str": "0",
            "reply_count": 0,
            "reply_count_str": "0",
            "like_count": 0,
            "like_count_str": "0",
            "quote_count": 0,
            "quote_count_str": "0",
            "bookmark_count": 0,
            "bookmark_count_str": "0",
            "impression_count": 0,
            "impression_count_str": "0"
          },
          "reply_settings": "everyone",
          "id": "2080765813578191303",
          "lang": "und"
        }
      ]
    }
  }
}
```

### `post.reply.create`

Fired when a user other than the filtered user posts a direct reply to a Post by the filtered user. Direct replies only (does not fire for replies to replies). Private event — requires user-context authentication with the `tweet.read` scope. The `payload` is a Post object for the reply; `includes` may contain related users and tweets (including the Post being replied to).

```json title="post.reply.create" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "3091827364059182736",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "post.reply.create",
    "tag": "replies",
    "payload": {
      "paid_partnership": false,
      "created_at": "2026-08-12T18:00:00.000Z",
      "edit_history_tweet_ids": [
        "2090000000000000001"
      ],
      "conversation_id": "2080761390344937796",
      "in_reply_to_tweet_id": "2080761390344937796",
      "in_reply_to_user_id": "1111111111111111111",
      "referenced_tweets": [
        {
          "type": "replied_to",
          "id": "2080761390344937796"
        }
      ],
      "display_text_range": [
        14,
        45
      ],
      "text": "@ExampleUser Great post — thanks for sharing!",
      "entities": {
        "mentions": [
          {
            "start": 0,
            "start_str": "0",
            "end": 12,
            "end_str": "12",
            "username": "ExampleUser",
            "id": "1111111111111111111"
          }
        ]
      },
      "author_id": "2222222222222222222",
      "possibly_sensitive": false,
      "public_metrics": {
        "retweet_count": 0,
        "retweet_count_str": "0",
        "reply_count": 0,
        "reply_count_str": "0",
        "like_count": 0,
        "like_count_str": "0",
        "quote_count": 0,
        "quote_count_str": "0",
        "bookmark_count": 0,
        "bookmark_count_str": "0",
        "impression_count": 0,
        "impression_count_str": "0"
      },
      "reply_settings": "everyone",
      "id": "2090000000000000001",
      "lang": "en"
    },
    "includes": {}
  }
}
```

### `post.quote.create`

Fired when a user other than the filtered user quote Posts a Post by the filtered user. Direct quotes only (does not fire for quotes of quotes). Private event — requires user-context authentication with the `tweet.read` scope. The `payload` is a Post object for the quote; `referenced_tweets` identifies the quoted Post.

```json title="post.quote.create" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "4172938465017283645",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "post.quote.create",
    "tag": "quotes",
    "payload": {
      "paid_partnership": false,
      "created_at": "2026-08-12T18:05:00.000Z",
      "edit_history_tweet_ids": [
        "2090000000000000002"
      ],
      "conversation_id": "2090000000000000002",
      "referenced_tweets": [
        {
          "type": "quoted",
          "id": "2080761390344937796"
        }
      ],
      "display_text_range": [
        0,
        29
      ],
      "text": "Adding some context to this. https://t.co/xxxxxxxx",
      "entities": {
        "urls": [
          {
            "start": 29,
            "start_str": "29",
            "end": 52,
            "end_str": "52",
            "url": "https://t.co/xxxxxxxx",
            "expanded_url": "https://twitter.com/ExampleUser/status/2080761390344937796",
            "display_url": "x.com/ExampleUser/st…"
          }
        ]
      },
      "author_id": "2222222222222222222",
      "possibly_sensitive": false,
      "public_metrics": {
        "retweet_count": 0,
        "retweet_count_str": "0",
        "reply_count": 0,
        "reply_count_str": "0",
        "like_count": 0,
        "like_count_str": "0",
        "quote_count": 0,
        "quote_count_str": "0",
        "bookmark_count": 0,
        "bookmark_count_str": "0",
        "impression_count": 0,
        "impression_count_str": "0"
      },
      "reply_settings": "everyone",
      "id": "2090000000000000002",
      "lang": "en"
    },
    "includes": {}
  }
}
```

### `post.repost.create`

Fired when a user other than the filtered user reposts a Post by the filtered user. Private event — requires user-context authentication with the `tweet.read` scope. The `payload` is a Post object for the repost; `referenced_tweets` with `type: "retweeted"` identifies the original Post.

```json title="post.repost.create" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "5283049576128394756",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "post.repost.create",
    "tag": "reposts",
    "payload": {
      "paid_partnership": false,
      "created_at": "2026-08-12T18:10:00.000Z",
      "edit_history_tweet_ids": [
        "2090000000000000003"
      ],
      "conversation_id": "2090000000000000003",
      "referenced_tweets": [
        {
          "type": "retweeted",
          "id": "2080761390344937796"
        }
      ],
      "display_text_range": [
        0,
        56
      ],
      "text": "RT @ExampleUser: Hello from the Activity API",
      "entities": {
        "mentions": [
          {
            "start": 3,
            "start_str": "3",
            "end": 15,
            "end_str": "15",
            "username": "ExampleUser",
            "id": "1111111111111111111"
          }
        ]
      },
      "author_id": "2222222222222222222",
      "possibly_sensitive": false,
      "public_metrics": {
        "retweet_count": 0,
        "retweet_count_str": "0",
        "reply_count": 0,
        "reply_count_str": "0",
        "like_count": 0,
        "like_count_str": "0",
        "quote_count": 0,
        "quote_count_str": "0",
        "bookmark_count": 0,
        "bookmark_count_str": "0",
        "impression_count": 0,
        "impression_count_str": "0"
      },
      "reply_settings": "everyone",
      "id": "2090000000000000003",
      "lang": "en"
    },
    "includes": {}
  }
}
```

<Note>
  **Protected accounts:** Posts from protected accounts are not delivered through XAA, even when the subscribing app has user-context authorization for the filtered user.
</Note>

<Note>
  **Billing:** Each delivered Post event (`post.create`, `post.delete`, `post.mention.create`, `post.reply.create`, `post.quote.create`, `post.repost.create`) is billed as a Post.
</Note>

***

## Like events

### `like.create`

Fired when the filtered user likes a Post, or when one of their Posts is liked. Private event — requires user-context authentication. Supports an optional `direction` filter (`inbound` or `outbound`).

The `payload` is a like object with the following fields:

| Field                   | Description                                      |
| ----------------------- | ------------------------------------------------ |
| `id`                    | Like event ID                                    |
| `liked_tweet_id`        | ID of the Post that was liked                    |
| `liked_tweet_author_id` | Author of the liked Post                         |
| `created_at`            | Creation time of the liked Post (when available) |
| `timestamp_ms`          | Event timestamp in milliseconds (when available) |

`includes` may contain the liked Post and related users.

```json title="like.create" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "-3402274206530057851",
    "filter": {
      "user_id": "1111111111111111111",
      "direction": "outbound"
    },
    "event_type": "like.create",
    "tag": "likes",
    "payload": {
      "id": "87719f50ee17bdfa06a3089098a2b9ed",
      "created_at": "2026-07-24T21:12:45.000Z",
      "timestamp_ms": "1784927565236",
      "liked_tweet_author_id": "3333333333333333333",
      "liked_tweet_id": "2079814480427442556"
    },
    "includes": {
      "users": [
        {
          "description": "𝕏 | @X @AnotherUser @XDevelopers",
          "pinned_tweet_id": "2040770361566826685",
          "url": "",
          "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
          "created_at": "2014-05-29T20:24:26.000Z",
          "entities": {
            "description": {
              "mentions": [
                {
                  "start": 4,
                  "start_str": "4",
                  "end": 6,
                  "end_str": "6",
                  "username": "X"
                },
                {
                  "start": 7,
                  "start_str": "7",
                  "end": 11,
                  "end_str": "11",
                  "username": "AnotherUser"
                },
                {
                  "start": 12,
                  "start_str": "12",
                  "end": 24,
                  "end_str": "24",
                  "username": "XDevelopers"
                }
              ]
            }
          },
          "public_metrics": {
            "followers_count": 26972,
            "followers_count_str": "26972",
            "following_count": 1713,
            "following_count_str": "1713",
            "tweet_count": 2994,
            "tweet_count_str": "2994",
            "listed_count": 297,
            "listed_count_str": "297",
            "like_count": 47468,
            "like_count_str": "47468",
            "media_count": 265,
            "media_count_str": "265"
          },
          "affiliation": {
            "description": "X",
            "url": "https://twitter.com/X",
            "user_id": [
              "783214"
            ],
            "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg"
          },
          "name": "Public User",
          "verified_type": "blue",
          "id": "3333333333333333333",
          "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
          "username": "PublicUser",
          "protected": false,
          "is_identity_verified": false,
          "location": "New York, NY",
          "verified": true,
          "profile_geo_enrichment": {
            "potential_locations": [
              {
                "geo_entity": {
                  "entity_id": "5391959",
                  "display_name": "San Francisco, California, United States",
                  "country_code": "US",
                  "region": "California",
                  "sub_region": "San Francisco County",
                  "locality": "San Francisco",
                  "population": 873965,
                  "population_str": "873965",
                  "geo_point": {
                    "latitude": 37.77493,
                    "longitude": -122.41942
                  }
                }
              }
            ]
          }
        }
      ],
      "tweets": [
        {
          "possibly_sensitive": false,
          "edit_controls": {
            "edits_remaining": 5,
            "edits_remaining_str": "5",
            "is_edit_eligible": true,
            "editable_until": "2026-07-22T07:23:07.000Z"
          },
          "lang": "en",
          "text": "Great guide on using the X AnotherUser via our new XMCP and Grok Build to build a structured knowledge system powered by X—unlocking great use cases like agentic research, realtime monitoring the situation, and an audience flywheel to improve as creators on X. https://t.co/5DedenNGo9",
          "conversation_id": "2079814480427442556",
          "created_at": "2026-07-22T06:23:07.000Z",
          "paid_partnership": false,
          "author_id": "3333333333333333333",
          "entities": {
            "urls": [
              {
                "start": 253,
                "start_str": "253",
                "end": 276,
                "end_str": "276",
                "url": "https://t.co/5DedenNGo9",
                "expanded_url": "https://twitter.com/xfreeze/status/2079756440722665849",
                "display_url": "x.com/xfreeze/status…"
              }
            ]
          },
          "edit_history_tweet_ids": [
            "2079814480427442556"
          ],
          "id": "2079814480427442556",
          "public_metrics": {
            "retweet_count": 16,
            "retweet_count_str": "16",
            "reply_count": 8,
            "reply_count_str": "8",
            "like_count": 131,
            "like_count_str": "131",
            "quote_count": 2,
            "quote_count_str": "2",
            "bookmark_count": 90,
            "bookmark_count_str": "90",
            "impression_count": 21004,
            "impression_count_str": "21004"
          },
          "referenced_tweets": [
            {
              "type": "quoted",
              "id": "2079756440722665849"
            }
          ],
          "display_text_range": [
            0,
            252
          ],
          "reply_settings": "everyone"
        }
      ]
    }
  }
}
```

***

## Follow events

### `follow.follow`

Fired when the filtered user follows another user, or is followed. The `payload` includes `source` (the follower) and `target` (the user being followed).

```json title="follow.follow" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "-7953119945885597316",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "follow.follow",
    "tag": "follows",
    "payload": {
      "source": {
        "data": {
          "affiliation": {
            "description": "X",
            "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
            "url": "https://twitter.com/X"
          },
          "location": "San Francisco, CA",
          "name": "Example User",
          "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
          "created_at": "2023-10-23T13:44:53.000Z",
          "protected": false,
          "verified": true,
          "url": "https://t.co/xxxxxxxx",
          "public_metrics": {
            "followers_count": 5502,
            "followers_count_str": "5502",
            "following_count": 652,
            "following_count_str": "652",
            "tweet_count": 790,
            "tweet_count_str": "790",
            "listed_count": 47,
            "listed_count_str": "47",
            "like_count": 8010,
            "like_count_str": "8010",
            "media_count": 79,
            "media_count_str": "79"
          },
          "is_identity_verified": true,
          "description": "Building with the X AnotherUser @XDevelopers",
          "verified_type": "blue",
          "entities": {
            "url": {
              "urls": [
                {
                  "start": 0,
                  "start_str": "0",
                  "end": 23,
                  "end_str": "23",
                  "url": "https://t.co/xxxxxxxx",
                  "expanded_url": "https://example.com",
                  "display_url": "https://example.com"
                }
              ]
            },
            "description": {
              "mentions": [
                {
                  "start": 49,
                  "start_str": "49",
                  "end": 51,
                  "end_str": "51",
                  "username": "X"
                },
                {
                  "start": 52,
                  "start_str": "52",
                  "end": 64,
                  "end_str": "64",
                  "username": "XDevelopers"
                }
              ]
            }
          },
          "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
          "username": "ExampleUser",
          "id": "1111111111111111111"
        }
      },
      "target": {
        "data": {
          "affiliation": {
            "description": "X",
            "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
            "url": "https://twitter.com/X"
          },
          "name": "AnotherUser",
          "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
          "created_at": "2007-05-23T06:01:13.000Z",
          "protected": false,
          "verified": true,
          "url": "https://t.co/YrfsitXdac",
          "public_metrics": {
            "followers_count": 4934564,
            "followers_count_str": "4934564",
            "following_count": 12,
            "following_count_str": "12",
            "tweet_count": 3755,
            "tweet_count_str": "3755",
            "listed_count": 11603,
            "listed_count_str": "11603",
            "like_count": 7,
            "like_count_str": "7",
            "media_count": 9,
            "media_count_str": "9"
          },
          "is_identity_verified": false,
          "description": "Updates about X AnotherUser changes and service issues.",
          "verified_type": "business",
          "entities": {
            "url": {
              "urls": [
                {
                  "start": 0,
                  "start_str": "0",
                  "end": 23,
                  "end_str": "23",
                  "url": "https://t.co/YrfsitXdac",
                  "expanded_url": "https://developer.x.com",
                  "display_url": "developer.x.com"
                }
              ]
            }
          },
          "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
          "username": "AnotherUser",
          "id": "4444444444444444444"
        }
      }
    }
  }
}
```

### `follow.unfollow`

Fired when the filtered user unfollows another user, or is unfollowed. Same `source` / `target` shape as `follow.follow`.

```json title="follow.unfollow" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "-4233426745281461957",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "follow.unfollow",
    "tag": "unfollows",
    "payload": {
      "source": {
        "data": {
          "affiliation": {
            "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
            "url": "https://twitter.com/X",
            "description": "X"
          },
          "url": "https://t.co/xxxxxxxx",
          "description": "Building with the X AnotherUser @XDevelopers",
          "verified": true,
          "entities": {
            "url": {
              "urls": [
                {
                  "start": 0,
                  "start_str": "0",
                  "end": 23,
                  "end_str": "23",
                  "url": "https://t.co/xxxxxxxx",
                  "expanded_url": "https://example.com",
                  "display_url": "https://example.com"
                }
              ]
            },
            "description": {
              "mentions": [
                {
                  "start": 49,
                  "start_str": "49",
                  "end": 51,
                  "end_str": "51",
                  "username": "X"
                },
                {
                  "start": 52,
                  "start_str": "52",
                  "end": 64,
                  "end_str": "64",
                  "username": "XDevelopers"
                }
              ]
            }
          },
          "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
          "is_identity_verified": true,
          "username": "ExampleUser",
          "id": "1111111111111111111",
          "name": "Example User",
          "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
          "created_at": "2023-10-23T13:44:53.000Z",
          "public_metrics": {
            "followers_count": 5502,
            "followers_count_str": "5502",
            "following_count": 651,
            "following_count_str": "651",
            "tweet_count": 790,
            "tweet_count_str": "790",
            "listed_count": 47,
            "listed_count_str": "47",
            "like_count": 8010,
            "like_count_str": "8010",
            "media_count": 79,
            "media_count_str": "79"
          },
          "verified_type": "blue",
          "location": "San Francisco, CA",
          "protected": false
        }
      },
      "target": {
        "data": {
          "affiliation": {
            "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
            "url": "https://twitter.com/X",
            "description": "X"
          },
          "url": "https://t.co/YrfsitXdac",
          "description": "Updates about X AnotherUser changes and service issues.",
          "verified": true,
          "entities": {
            "url": {
              "urls": [
                {
                  "start": 0,
                  "start_str": "0",
                  "end": 23,
                  "end_str": "23",
                  "url": "https://t.co/YrfsitXdac",
                  "expanded_url": "https://developer.x.com",
                  "display_url": "developer.x.com"
                }
              ]
            }
          },
          "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
          "is_identity_verified": false,
          "username": "AnotherUser",
          "id": "4444444444444444444",
          "name": "AnotherUser",
          "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
          "created_at": "2007-05-23T06:01:13.000Z",
          "public_metrics": {
            "followers_count": 4934563,
            "followers_count_str": "4934563",
            "following_count": 12,
            "following_count_str": "12",
            "tweet_count": 3755,
            "tweet_count_str": "3755",
            "listed_count": 11603,
            "listed_count_str": "11603",
            "like_count": 7,
            "like_count_str": "7",
            "media_count": 9,
            "media_count_str": "9"
          },
          "verified_type": "business",
          "protected": false
        }
      }
    }
  }
}
```

***

## Profile events

All `profile.update.*` events share a `before` / `after` payload shape.

Supported types: `profile.update.bio`, `profile.update.profile_picture`, `profile.update.banner_picture`, `profile.update.screenname`, `profile.update.handle`, `profile.update.geo`, `profile.update.url`, `profile.update.verified_badge`, `profile.update.affiliate_badge`.

### `profile.update.bio`

Fired when the filtered user updates their profile bio.

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "-8917909039855612786",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "profile.update.bio",
    "tag": "profile-bio",
    "payload": {
      "before": "Building with the X API",
      "after": "Building with the X API @XDevelopers"
    }
  }
}
```

### `profile.update.profile_picture`

Fired when the filtered user updates their profile picture.

```json title="profile.update.profile_picture" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "3497989179769309099",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "profile.update.profile_picture",
    "tag": "profile-picture",
    "payload": {
      "before": "https://pbs.twimg.com/profile_images/0000000000000000001/old_normal.jpg",
      "after": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg"
    }
  }
}
```

### `profile.update.banner_picture`

Fired when the filtered user updates their profile banner.

```json title="profile.update.banner_picture" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "5061407317112342192",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "profile.update.banner_picture",
    "tag": "profile-banner",
    "payload": {
      "before": "https://pbs.twimg.com/profile_banners/1111111111111111111/1500000000",
      "after": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000"
    }
  }
}
```

### `profile.update.screenname`

Fired when the filtered user updates their display name.

```json title="profile.update.screenname" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "4123434298221215973",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "profile.update.screenname",
    "tag": "profile-name",
    "payload": {
      "before": "Example User",
      "after": "Example"
    }
  }
}
```

### `profile.update.geo`

Fired when the filtered user updates their profile location.

```json title="profile.update.geo" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "8309664692915093892",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "profile.update.geo",
    "tag": "profile-location",
    "payload": {
      "before": "New York, NY",
      "after": "San Francisco, CA"
    }
  }
}
```

### `profile.update.url`

Fired when the filtered user updates their profile website URL.

```json title="profile.update.url" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "-6055744140117128555",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "profile.update.url",
    "tag": "profile-url",
    "payload": {
      "before": "https://t.co/oldlinkxx",
      "after": "https://t.co/xxxxxxxx"
    }
  }
}
```

### `profile.update.handle`

Fired when the filtered user updates their @handle. Same `before` / `after` payload shape as other profile events.

### `profile.update.verified_badge`

Fired when the filtered user's verified badge changes. Same `before` / `after` payload shape as other profile events.

### `profile.update.affiliate_badge`

Fired when the filtered user's affiliate badge changes. Same `before` / `after` payload shape as other profile events.

***

## Chat events (XChat)

Encrypted chat payloads include opaque encoded fields used by the XChat client libraries. Private events — require user-context authentication. Encoded crypto fields below are truncated for readability; real deliveries include the full strings.

### `chat.received`

```json title="chat.received" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "8511582263942905822",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "chat.received",
    "tag": "chat-inbound",
    "payload": {
      "conversation_token": "eyJhbGciOiJIUzI1NiJ9.eyJyZXF1ZXN0aW5nVXN…(truncated)",
      "id": "e4f4d3fc-8bbf-4928-92eb-e5058d6bb6f6",
      "created_at_msec": "1784841183370",
      "sender_id": "2222222222222222222",
      "conversation_id": "2222222222222222222:1111111111111111111",
      "conversation_key_version": "1768236281331",
      "encoded_event": "CwABAAAAEzIwODA0MDA4MjUyMjcxMDAxNjALAAIA…(truncated)",
      "conversation_key_change_event": "CwABAAAAEzIwMTA3NTQ4MTkxMTY0NDk5MDULAAIA…(truncated)",
      "message_event_signature": {
        "public_key_version": "1765382634817",
        "signature": "6IK9SZIMXBe5SFcB7vGZJd5A5Eb5MLvnwrhUFfBGv4S5GsSX3WWPGuInXVNfSla36EjXQQ/R/HhsA+2hPAEY7A",
        "signature_version": "7",
        "signing_public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJ2c+3BYZs7ZCEY/UPCpmQxJO9v6FJjeusvmSZO/JEay8oF1+oXXlHV55kX4bK6/zFijNKvq1YRb0it0yXqbglA=="
      }
    }
  }
}
```

### `chat.sent`

```json title="chat.sent" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "3723060601307155846",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "chat.sent",
    "tag": "chat-outbound",
    "payload": {
      "conversation_token": "eyJhbGciOiJIUzI1NiJ9.eyJyZXF1ZXN0aW5nVXN…(truncated)",
      "id": "8e75466b-56ec-4e88-bddf-b18f7cc6030e",
      "created_at_msec": "1784841233939",
      "sender_id": "1111111111111111111",
      "conversation_id": "2222222222222222222:1111111111111111111",
      "conversation_key_version": "1768236281331",
      "encoded_event": "CwABAAAAEzIwODA0MDEwMzczMzMyMzc3NjALAAIA…(truncated)",
      "conversation_key_change_event": "CwABAAAAEzIwMTA3NTQ4MTkxMTY0NDk5MDULAAIA…(truncated)",
      "message_event_signature": {
        "public_key_version": "1736723828667",
        "signature": "ManuRvBupip38XzgS733V9xVn/6+4uguMwvMa+YUDQiDIxVhVbaQcN+bKybPRBCj7IPuRi2QQzRvPg7Wq9ZhPw",
        "signature_version": "7",
        "signing_public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEyxQY+3CI2lwMF5EqRWc6XMRnYmTnaQXhQy1ozchz0IQn7ui5ry1USzScT900WyTPkNmSvG+M8txz+8Y5Wf0gZQ=="
      }
    }
  }
}
```

### `chat.conversation_join`

Fired when a user joins an encrypted chat conversation. The payload shape matches other chat events (conversation identity and encoded crypto material). Private event — requires user-context authentication.

***

## Legacy DM events

Legacy (unencrypted) DM events. Private events — require user-context authentication.

### `dm.sent`

Fired when the filtered user sends an unencrypted DM. The `payload` includes `direct_message_events` and a `users` map.

```json title="dm.sent" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "-3577827201104920132",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "dm.sent",
    "tag": "dm-outbound",
    "payload": {
      "direct_message_events": [
        {
          "type": "message_create",
          "id": "2080763914820927863",
          "created_timestamp": "1784927750704",
          "message_create": {
            "target": {
              "recipient_id": "2244994945"
            },
            "sender_id": "1111111111111111111",
            "message_data": {
              "text": "Thanks for the update!",
              "entities": {
                "hashtags": [],
                "symbols": [],
                "user_mentions": [],
                "urls": []
              }
            }
          }
        }
      ],
      "users": {
        "1111111111111111111": {
          "data": {
            "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
            "username": "ExampleUser",
            "affiliation": {
              "description": "X",
              "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
              "url": "https://twitter.com/X"
            },
            "name": "Example User",
            "verified_type": "blue",
            "description": "Building with the X AnotherUser @XDevelopers",
            "location": "San Francisco, CA",
            "public_metrics": {
              "followers_count": 5502,
              "followers_count_str": "5502",
              "following_count": 651,
              "following_count_str": "651",
              "tweet_count": 789,
              "tweet_count_str": "789",
              "listed_count": 47,
              "listed_count_str": "47",
              "like_count": 8010,
              "like_count_str": "8010",
              "media_count": 79,
              "media_count_str": "79"
            },
            "id": "1111111111111111111",
            "url": "https://t.co/xxxxxxxx",
            "protected": false,
            "created_at": "2023-10-23T13:44:53.000Z",
            "is_identity_verified": true,
            "verified": true,
            "entities": {
              "url": {
                "urls": [
                  {
                    "start": 0,
                    "start_str": "0",
                    "end": 23,
                    "end_str": "23",
                    "url": "https://t.co/xxxxxxxx",
                    "expanded_url": "https://example.com",
                    "display_url": "https://example.com"
                  }
                ]
              },
              "description": {
                "mentions": [
                  {
                    "start": 49,
                    "start_str": "49",
                    "end": 51,
                    "end_str": "51",
                    "username": "X"
                  },
                  {
                    "start": 52,
                    "start_str": "52",
                    "end": 64,
                    "end_str": "64",
                    "username": "XDevelopers"
                  }
                ]
              }
            },
            "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg"
          }
        },
        "2244994945": {
          "data": {
            "profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1690213128",
            "username": "XDevelopers",
            "affiliation": {
              "description": "X",
              "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
              "url": "https://twitter.com/X"
            },
            "name": "X Developers",
            "verified_type": "business",
            "description": "The voice of the X Dev team and your official source for updates, news, and events, related to the X AnotherUser.",
            "location": "127.0.0.1",
            "public_metrics": {
              "followers_count": 694887,
              "followers_count_str": "694887",
              "following_count": 762,
              "following_count_str": "762",
              "tweet_count": 4309,
              "tweet_count_str": "4309",
              "listed_count": 2978,
              "listed_count_str": "2978",
              "like_count": 2626,
              "like_count_str": "2626",
              "media_count": 829,
              "media_count_str": "829"
            },
            "id": "2244994945",
            "url": "https://t.co/NIwHVIVyrN",
            "protected": false,
            "created_at": "2013-12-14T04:35:55.000Z",
            "is_identity_verified": false,
            "verified": true,
            "entities": {
              "url": {
                "urls": [
                  {
                    "start": 0,
                    "start_str": "0",
                    "end": 23,
                    "end_str": "23",
                    "url": "https://t.co/NIwHVIVyrN",
                    "expanded_url": "https://docs.x.com/",
                    "display_url": "docs.x.com"
                  }
                ]
              }
            },
            "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg"
          }
        }
      }
    }
  }
}
```

### `dm.received`

Fired when the filtered user receives an unencrypted DM. Same payload shape as `dm.sent` (`direct_message_events` plus a `users` map). Private event — requires user-context authentication.

```json title="dm.received" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "-6850472171600526495",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "dm.received",
    "tag": "dm-inbound",
    "payload": {
      "direct_message_events": [
        {
          "type": "message_create",
          "id": "2080765901528535096",
          "created_timestamp": "1784928224372",
          "message_create": {
            "target": {
              "recipient_id": "1111111111111111111"
            },
            "sender_id": "2222222222222222222",
            "message_data": {
              "text": "hello!",
              "entities": {
                "hashtags": [],
                "symbols": [],
                "user_mentions": [],
                "urls": []
              }
            }
          }
        }
      ],
      "users": {
        "2222222222222222222": {
          "data": {
            "description": "",
            "profile_banner_url": "",
            "public_metrics": {
              "followers_count": 97,
              "followers_count_str": "97",
              "following_count": 1,
              "following_count_str": "1",
              "tweet_count": 50,
              "tweet_count_str": "50",
              "listed_count": 4,
              "listed_count_str": "4",
              "like_count": 27,
              "like_count_str": "27",
              "media_count": 3,
              "media_count_str": "3"
            },
            "protected": false,
            "url": "",
            "affiliation": {
              "description": "Automated",
              "badge_url": "https://pbs.twimg.com/semantic_core_img/1428827730364096519/4ZXpTBhS?format=png&name=orig"
            },
            "is_identity_verified": false,
            "id": "2222222222222222222",
            "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
            "verified_type": "none",
            "created_at": "2026-04-20T19:55:59.000Z",
            "username": "OtherUser",
            "verified": false,
            "name": "OtherUser"
          }
        },
        "1111111111111111111": {
          "data": {
            "description": "Building with the X AnotherUser @XDevelopers",
            "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
            "entities": {
              "url": {
                "urls": [
                  {
                    "start": 0,
                    "start_str": "0",
                    "end": 23,
                    "end_str": "23",
                    "url": "https://t.co/xxxxxxxx",
                    "expanded_url": "https://developer.x.com",
                    "display_url": "developer.x.com"
                  }
                ]
              },
              "description": {
                "mentions": [
                  {
                    "start": 48,
                    "start_str": "48",
                    "end": 50,
                    "end_str": "50",
                    "username": "X"
                  },
                  {
                    "start": 51,
                    "start_str": "51",
                    "end": 63,
                    "end_str": "63",
                    "username": "XDevelopers"
                  }
                ]
              }
            },
            "public_metrics": {
              "followers_count": 5502,
              "followers_count_str": "5502",
              "following_count": 651,
              "following_count_str": "651",
              "tweet_count": 789,
              "tweet_count_str": "789",
              "listed_count": 46,
              "listed_count_str": "46",
              "like_count": 8010,
              "like_count_str": "8010",
              "media_count": 79,
              "media_count_str": "79"
            },
            "location": "San Francisco, CA",
            "protected": false,
            "url": "https://t.co/xxxxxxxx",
            "affiliation": {
              "description": "X",
              "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
              "url": "https://twitter.com/X"
            },
            "is_identity_verified": true,
            "id": "1111111111111111111",
            "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
            "verified_type": "blue",
            "created_at": "2023-10-23T13:44:53.000Z",
            "username": "ExampleUser",
            "verified": true,
            "name": "Example User"
          }
        }
      }
    }
  }
}
```

### `dm.read`

Fired when a participant reads the filtered user's unencrypted DM (read receipt). Private event — requires user-context authentication.

### `dm.indicate_typing`

Fired when a participant is typing a message to the filtered user. Private event — requires user-context authentication.

***

## News events

### `news.new`

Filter by `keyword`. The `payload` includes Grok-curated news fields such as category, name, hook, summary, contexts, and related cluster post results.

| Field                   | Description                     |
| ----------------------- | ------------------------------- |
| `id`                    | News item ID                    |
| `name`                  | Headline / topic name           |
| `category`              | News category                   |
| `hook`                  | Short hook / teaser             |
| `summary`               | Longer summary                  |
| `contexts`              | Related topic / entity contexts |
| `cluster_posts_results` | Related Posts when available    |
| `updated_at`            | Last update timestamp           |
| `disclaimer`            | Optional disclaimer text        |

```json title="news.new" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "2080756868147019827",
    "filter": {
      "keyword": "OpenAI"
    },
    "event_type": "news.new",
    "tag": "news-keyword",
    "payload": {
      "summary": "OpenAI rolled out a new feature in ChatGPT's web version that lets users create virtual pets by describing them, generating fun companions like a fluffy gray cat or a seal in a yellow bow tie. Creators can copy a shareable link from…",
      "contexts": {
        "entities": {
          "events": [],
          "organizations": [
            "OpenAI"
          ],
          "people": [],
          "places": [],
          "products": []
        },
        "topics": [
          "Technology"
        ],
        "finance": {
          "tickers": []
        },
        "sports": {
          "teams": []
        }
      },
      "id": "2080756868147019827",
      "updated_at": "2026-07-24T20:53:37.000Z",
      "hook": "Imagine designing a green dinosaur with a bow tie, then sharing it with friends to adopt as their own ChatGPT companion.",
      "category": "News",
      "disclaimer": "This story is a summary of posts on X and may evolve over time. Grok can make mistakes, verify its outputs.",
      "cluster_posts_results": [
        {
          "post_id": "2080756403493560652"
        },
        {
          "post_id": "2080747505474736162"
        },
        {
          "post_id": "2080750142437880021"
        }
      ],
      "name": "ChatGPT Adds Custom Virtual Pets for Sharing"
    }
  }
}
```

***

## Spaces events

### `spaces.start`

Fired when the filtered user starts a Space. The `payload` includes the host `user`, `broadcast_id`, and an inner `event_type` of `start`.

```json title="spaces.start" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "4093201169289922041",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "spaces.start",
    "tag": "spaces-start",
    "payload": {
      "user": {
        "data": {
          "affiliation": {
            "description": "X",
            "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
            "url": "https://twitter.com/X"
          },
          "location": "San Francisco, CA",
          "name": "Example User",
          "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
          "created_at": "2023-10-23T13:44:53.000Z",
          "protected": false,
          "verified": true,
          "url": "https://t.co/xxxxxxxx",
          "public_metrics": {
            "followers_count": 5502,
            "followers_count_str": "5502",
            "following_count": 651,
            "following_count_str": "651",
            "tweet_count": 789,
            "tweet_count_str": "789",
            "listed_count": 46,
            "listed_count_str": "46",
            "like_count": 8010,
            "like_count_str": "8010",
            "media_count": 79,
            "media_count_str": "79"
          },
          "is_identity_verified": true,
          "description": "Building with the X AnotherUser @XDevelopers",
          "verified_type": "blue",
          "entities": {
            "url": {
              "urls": [
                {
                  "start": 0,
                  "start_str": "0",
                  "end": 23,
                  "end_str": "23",
                  "url": "https://t.co/xxxxxxxx",
                  "expanded_url": "https://developer.x.com",
                  "display_url": "developer.x.com"
                }
              ]
            },
            "description": {
              "mentions": [
                {
                  "start": 48,
                  "start_str": "48",
                  "end": 50,
                  "end_str": "50",
                  "username": "X"
                },
                {
                  "start": 51,
                  "start_str": "51",
                  "end": 63,
                  "end_str": "63",
                  "username": "XDevelopers"
                }
              ]
            }
          },
          "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
          "username": "ExampleUser",
          "id": "1111111111111111111"
        }
      },
      "broadcast_id": "1qxvvvyLLdnxB",
      "event_type": "spaces_start"
    }
  }
}
```

### `spaces.end`

Fired when the filtered user ends a Space. Same shape as `spaces.start` with an inner `event_type` of `end`.

```json title="spaces.end" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "-498317022904955631",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "spaces.end",
    "tag": "spaces-end",
    "payload": {
      "user": {
        "data": {
          "description": "Building with the X AnotherUser @XDevelopers",
          "protected": false,
          "is_identity_verified": true,
          "affiliation": {
            "url": "https://twitter.com/X",
            "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
            "description": "X"
          },
          "entities": {
            "url": {
              "urls": [
                {
                  "start": 0,
                  "start_str": "0",
                  "end": 23,
                  "end_str": "23",
                  "url": "https://t.co/xxxxxxxx",
                  "expanded_url": "https://developer.x.com",
                  "display_url": "developer.x.com"
                }
              ]
            },
            "description": {
              "mentions": [
                {
                  "start": 48,
                  "start_str": "48",
                  "end": 50,
                  "end_str": "50",
                  "username": "X"
                },
                {
                  "start": 51,
                  "start_str": "51",
                  "end": 63,
                  "end_str": "63",
                  "username": "XDevelopers"
                }
              ]
            }
          },
          "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
          "public_metrics": {
            "followers_count": 5502,
            "followers_count_str": "5502",
            "following_count": 651,
            "following_count_str": "651",
            "tweet_count": 789,
            "tweet_count_str": "789",
            "listed_count": 46,
            "listed_count_str": "46",
            "like_count": 8010,
            "like_count_str": "8010",
            "media_count": 79,
            "media_count_str": "79"
          },
          "id": "1111111111111111111",
          "verified_type": "blue",
          "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
          "name": "Example User",
          "url": "https://t.co/xxxxxxxx",
          "username": "ExampleUser",
          "location": "San Francisco, CA",
          "verified": true,
          "created_at": "2023-10-23T13:44:53.000Z"
        }
      },
      "broadcast_id": "1qxvvvyLLdnxB",
      "event_type": "spaces_end"
    }
  }
}
```

***

## Mute events

Mute events use a `source` / `target` user pair similar to follow events. Private events — require user-context authentication with the `mute.read` scope. The `user_id` filter matches the user **performing** the mute or unmute (not the account being muted).

### `mute.mute`

Fired when the filtered user mutes another user.

### `mute.unmute`

Fired when the filtered user unmutes another user.

***

## Block events

Block events use a `source` / `target` user pair similar to follow events. Private events — require user-context authentication with the `block.read` scope. The `user_id` filter matches the user **performing** the block or unblock (not the account being blocked).

### `block.block`

Fired when the filtered user blocks another user.

### `block.unblock`

Fired when the filtered user unblocks another user.

***

## Broadcast events

### `broadcast.chat`

Fired when the filtered user receives a chat message in a broadcast that they own. Private event — requires user-context authentication with the `broadcast.read` scope. The `payload` includes the `broadcast_id`, the chat `message_id` and `message` text, and an `author` block with the sending user's profile.

```json title="broadcast.chat" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "7365873565827875221",
    "filter": {
      "user_id": "1111111111111111111"
    },
    "event_type": "broadcast.chat",
    "tag": "my stream chats",
    "payload": {
      "broadcast_id": "1mGPaZaAdNqJN",
      "message_id": "2090000000000000004",
      "message": "test",
      "author": {
        "data": {
          "affiliation": {
            "url": "https://twitter.com/X",
            "badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
            "description": "X"
          },
          "created_at": "2024-08-31T23:23:51.000Z",
          "is_identity_verified": false,
          "id": "1111111111111111111",
          "username": "ExampleUser",
          "profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
          "verified_type": "blue",
          "public_metrics": {
            "followers_count": 2774,
            "followers_count_str": "2774",
            "following_count": 268,
            "following_count_str": "268",
            "tweet_count": 705,
            "tweet_count_str": "705",
            "listed_count": 42,
            "listed_count_str": "42",
            "like_count": 983,
            "like_count_str": "983",
            "media_count": 93,
            "media_count_str": "93"
          },
          "profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
          "name": "Example User",
          "entities": {
            "url": {
              "urls": [
                {
                  "start": 0,
                  "start_str": "0",
                  "end": 23,
                  "end_str": "23",
                  "url": "https://t.co/xxxxxxxx",
                  "expanded_url": "https://example.com",
                  "display_url": "example.com"
                }
              ]
            },
            "description": {
              "mentions": [
                {
                  "start": 19,
                  "start_str": "19",
                  "end": 21,
                  "end_str": "21",
                  "username": "X"
                }
              ]
            }
          },
          "protected": false,
          "url": "https://t.co/xxxxxxxx",
          "description": "Developer Platform @X",
          "verified": true
        }
      }
    }
  }
}
```

***

## OAuth events

### `oauth.revoke`

Fired when a user revokes your application's access. The `filter` may be empty. Use this to clean up local state for the revoked user.

```json title="oauth.revoke" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_uuid": "5934540941047412905",
    "filter": {},
    "event_type": "oauth.revoke",
    "payload": {
      "date_time": "2026-07-23T21:44:05+00:00",
      "user_id": "1111111111111111111",
      "app_id": "29820954"
    }
  }
}
```

***

## Next steps

<CardGroup>
  <Card title="Introduction" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/activity/introduction">
    Supported event types, privacy, and authentication
  </Card>

  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/activity/quickstart">
    Create a subscription and receive events
  </Card>

  <Card title="Activity stream" icon="water" href="/x-api/activity/activity-stream">
    Connect to the persistent HTTP stream
  </Card>

  <Card title="Webhooks" icon="webhook" href="/x-api/webhooks/introduction">
    Deliver activity events to your webhook URL
  </Card>
</CardGroup>


# Get X activity subscriptions
Source: https://docs.x.com/x-api/activity/get-x-activity-subscriptions

get /2/activity/subscriptions
Get a list of active subscriptions for XAA



# X Activity API for streaming user event data
Source: https://docs.x.com/x-api/activity/introduction

Stream real-time user activity events from the X Platform, including posts, likes, follows, mutes, blocks, DMs, mentions, and profile updates via webhooks.

<BlueprintMark name="broadcast" />

The X Activity API (XAA) endpoint group allows developers to tap into activity events happening on the X Platform.

You can subscribe to events you are interested in, such as `profile.update.bio`, `post.create`, or `post.delete`, and filter by the User ID whose events you want. XAA delivers matching events for that User ID to your app with sub-second latency.

## Delivery mechanisms

The X Activity API currently supports the following delivery mechanisms to send events to your app:

* Persistent HTTP stream
* [Webhook](/x-api/webhooks/introduction)

## Supported event types

Currently, X Activity API supports the following event types, organized by category. For sample JSON for each type, see [Event payloads](/x-api/activity/event-payloads).

### Post events

Post events are triggered when the filtered user creates or deletes a Post, or when another user interacts with the filtered user's Posts (replies, quotes, reposts, and @mentions).

| Event Name            | Description                                                                                                                                                                                                                                    | Filters   |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `post.create`         | Fired when the filtered user creates a Post. Fires for standalone Posts, replies, quote Posts, and reposts by the filtered user. Inspect the payload (for example `in_reply_to_tweet_id` or `referenced_tweets`) to distinguish the Post type. | `user_id` |
| `post.delete`         | Fired when the filtered user deletes a Post                                                                                                                                                                                                    | `user_id` |
| `post.mention.create` | Fired when another user explicitly @mentions the filtered user in the body of a Post. Does not fire for implicit mentions carried by replies or reposts.                                                                                       | `user_id` |
| `post.reply.create`   | Fired when a user other than the filtered user posts a direct reply to a Post by the filtered user. Direct replies only (does not fire for replies to replies).                                                                                | `user_id` |
| `post.quote.create`   | Fired when a user other than the filtered user quote Posts a Post by the filtered user. Direct quotes only (does not fire for quotes of quotes).                                                                                               | `user_id` |
| `post.repost.create`  | Fired when a user other than the filtered user reposts a Post by the filtered user.                                                                                                                                                            | `user_id` |

<Note>
  **Protected accounts:** Posts from protected accounts are not delivered through XAA, even when the subscribing app has user-context authorization for the filtered user.
</Note>

<Note>
  **Post events via XAA vs Filtered Stream:** X Activity API delivers per-user Post activity by `user_id`. Subscribe to get real-time notifications when the filtered user creates or deletes Posts, or when other users reply to, quote, repost, or @mention them.

  If you want targeted keyword filtering, boolean logic, geo targeting, language filters, or any of the other operators that the Filtered Stream supports, use the [Filtered Stream](/x-api/posts/filtered-stream/introduction) endpoint instead.
</Note>

<Note>
  **Billing:** Each delivered Post event (`post.create`, `post.delete`, `post.mention.create`, `post.reply.create`, `post.quote.create`, `post.repost.create`) is billed as a Post.
</Note>

### Like events

Like events are triggered when a user likes a Post, or when one of the user's own Posts is liked.

| Event Name    | Description                                                    | Filters                |
| ------------- | -------------------------------------------------------------- | ---------------------- |
| `like.create` | Fired when a user likes a Post, or one of their Posts is liked | `user_id`, `direction` |

<Note>
  **Direction filter:** The `like.create` event supports an optional `direction` filter set to `outbound` or `inbound`. Use `outbound` for likes the user makes, and `inbound` for likes the user's Posts receive. If no `direction` is specified, both inbound and outbound like events are delivered.

  **Private event:** `like.create` is a private event and requires user-context (OAuth 2.0) authentication. See [Event privacy and authentication](#event-privacy-and-authentication) below.
</Note>

### Follow events

Follow events are triggered when the filtered user follows another user, or is followed by another user.

| Event Name        | Description                              | Filters   |
| ----------------- | ---------------------------------------- | --------- |
| `follow.follow`   | Fired when a user follows another user   | `user_id` |
| `follow.unfollow` | Fired when a user unfollows another user | `user_id` |

### Profile events

Profile events are triggered when a user makes changes to their profile information.

| Event Name                       | Description                                         | Filters   |
| -------------------------------- | --------------------------------------------------- | --------- |
| `profile.update.bio`             | Fired when a user updates their profile bio         | `user_id` |
| `profile.update.profile_picture` | Fired when a user updates their profile picture     | `user_id` |
| `profile.update.banner_picture`  | Fired when a user updates their profile banner      | `user_id` |
| `profile.update.screenname`      | Fired when a user updates their display name        | `user_id` |
| `profile.update.handle`          | Fired when a user updates their handle              | `user_id` |
| `profile.update.geo`             | Fired when a user updates their profile location    | `user_id` |
| `profile.update.url`             | Fired when a user updates their profile website URL | `user_id` |
| `profile.update.verified_badge`  | Fired when a user updates their verified badge      | `user_id` |
| `profile.update.affiliate_badge` | Fired when a user updates their affiliate badge     | `user_id` |

### Chat events

Chat events pertain to the new, encrypted messaging stack, or XChat.

| Event Name               | Description                                            | Filters   |
| ------------------------ | ------------------------------------------------------ | --------- |
| `chat.received`          | Fired when a user receives an encrypted direct message | `user_id` |
| `chat.sent`              | Fired when a user sends an encrypted direct message    | `user_id` |
| `chat.conversation_join` | Fired when a user joins an encrypted chat conversation | `user_id` |

### Legacy DM events

Legacy DM events pertain to the legacy, unencrypted DM system.

| Event Name           | Description                                                                           | Filters   |
| -------------------- | ------------------------------------------------------------------------------------- | --------- |
| `dm.received`        | Fired when a user receives an unencrypted direct message                              | `user_id` |
| `dm.sent`            | Fired when a user sends an unencrypted direct message                                 | `user_id` |
| `dm.read`            | Fired when a user reads the filtered user's unencrypted DM message, or "read receipt" | `user_id` |
| `dm.indicate_typing` | Fired when a user is typing a message to the filtered user                            | `user_id` |

### News events

News events provide updates on trending topics and headlines curated by Grok.

| Event Name | Description                           | Filters   |
| ---------- | ------------------------------------- | --------- |
| `news.new` | New grok-curated trends and headlines | `keyword` |

<Note>
  **Enterprise only:** The `news.new` event is only available to Enterprise and Partner tier accounts at this time.
</Note>

### Spaces events

Spaces events are triggered when a user starts or ends a Space.

| Event Name     | Description                      | Filters   |
| -------------- | -------------------------------- | --------- |
| `spaces.start` | Fired when a user starts a Space | `user_id` |
| `spaces.end`   | Fired when a user ends a Space   | `user_id` |

### Mute events

Mute events are triggered when the filtered user mutes or unmutes another user.

| Event Name    | Description                            | Filters   |
| ------------- | -------------------------------------- | --------- |
| `mute.mute`   | Fired when a user mutes another user   | `user_id` |
| `mute.unmute` | Fired when a user unmutes another user | `user_id` |

<Note>
  **Private events:** Mute events are private and require user-context (OAuth 2.0) authentication with the `mute.read` scope. The `user_id` filter matches the user performing the mute or unmute — you cannot subscribe to notifications about a user *being* muted. See [Event privacy and authentication](#event-privacy-and-authentication) below.
</Note>

### Block events

Block events are triggered when the filtered user blocks or unblocks another user.

| Event Name      | Description                             | Filters   |
| --------------- | --------------------------------------- | --------- |
| `block.block`   | Fired when a user blocks another user   | `user_id` |
| `block.unblock` | Fired when a user unblocks another user | `user_id` |

<Note>
  **Private events:** Block events are private and require user-context (OAuth 2.0) authentication with the `block.read` scope. The `user_id` filter matches the user performing the block or unblock — you cannot subscribe to notifications about a user *being* blocked. See [Event privacy and authentication](#event-privacy-and-authentication) below.
</Note>

### Broadcast events

Broadcast events are triggered when the filtered user receives a chat message in a broadcast that they own.

| Event Name       | Description                                                                       | Filters   |
| ---------------- | --------------------------------------------------------------------------------- | --------- |
| `broadcast.chat` | Fired when the filtered user receives a chat message in a broadcast that they own | `user_id` |

<Note>
  **Private event:** `broadcast.chat` is a private event and requires user-context (OAuth 2.0) authentication with the `broadcast.read` scope. See [Event privacy and authentication](#event-privacy-and-authentication) below.
</Note>

### OAuth events

OAuth events are triggered when a user revokes your application's access.

| Event Name     | Description                                 | Filters |
| -------------- | ------------------------------------------- | ------- |
| `oauth.revoke` | Fired when a user revokes app authorization | none    |

In future releases, XAA will expand to support additional event types including social interactions, content engagement, monetization features, and more. We will continue to update our docs when new event types become available.

## Event privacy and authentication

The X Activity API distinguishes between **public events** and **private events**, at parity with the X app, as explained below.

### Public events

Public events are activities that a public user account performs publicly that are visible to all X users. These events are visible to all users on the X platform and don't require OAuth authentication from the user in order to view.

**Current public events:**

* Profile updates (bio, picture, banner, location, URL, username changes)
* Post creation (`post.create`) and deletion (`post.delete`)

For these public events, you can create subscriptions by specifying the user ID in your filter and receive them via XAA.

Posts from protected accounts are not delivered, even for public events.

### Private events

Private events are activities that require explicit user consent through OAuth authentication. A user must authenticate via X and grant explicit permission to a developer app to access these events.

**Current private events:**

* Likes (`like.create`)
* Encrypted chat received (`chat.received`)
* Encrypted chat sent (`chat.sent`)
* DM received (`dm.received`)
* DM sent (`dm.sent`)
* DM read (`dm.read`)
* DM typing indicator (`dm.indicate_typing`)
* Post mentions (`post.mention.create`) — requires the `tweet.read` scope
* Post replies (`post.reply.create`) — requires the `tweet.read` scope
* Post quotes (`post.quote.create`) — requires the `tweet.read` scope
* Post reposts (`post.repost.create`) — requires the `tweet.read` scope
* Mutes (`mute.mute`, `mute.unmute`) — requires the `mute.read` scope
* Blocks (`block.block`, `block.unblock`) — requires the `block.read` scope
* Broadcast chats (`broadcast.chat`) — requires the `broadcast.read` scope

**Authentication requirements for private events:**

* The user must authenticate your application via OAuth 2.0
* Your application must obtain appropriate OAuth scopes
* The user must explicitly grant permission for your app to access these events
* Subscriptions for private events can only be created for users who have authorized your application

## Subscription limits

The X Activity API has different subscription limits based on your account tier:

| Package Tier | Maximum Subscriptions |
| ------------ | --------------------- |
| Self-serve   | 1,500                 |
| Enterprise   | 75,000                |
| Partner      | 150,000               |

## Endpoints

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

<Note>
  **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](/fundamentals/developer-apps) that is located within a Project.

  Learn more about getting access to the X API v2 endpoints in our [getting started guide](/x-api/getting-started/getting-access).
</Note>

<div>
  <Button href="/x-api/activity/quickstart">
    Quick start
  </Button>

  <Button href="/x-api/activity/event-payloads">
    Event payloads
  </Button>
</div>


# X Activity API quickstart guide for streaming events
Source: https://docs.x.com/x-api/activity/quickstart

This guide explains how to subscribe for and receive events using the X Activity API endpoints. Reference for the X API v2 standard tier covering activity.

This guide explains how to subscribe for and receive events using the X Activity API endpoints. There are generally 3 steps involved:

1. Identify the User ID for the User whose events you want to filter on
2. Create a subscription for the type of event you want to filter for that User
3. Receive the events using webhook or persistent http stream connection

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's [Bearer Token](/resources/fundamentals/authentication)
</Note>

***

## Getting user IDs

Before creating subscriptions, you'll need to know the user ID of the account you want to filter on. In this example, we will use the XDevelopers handle. You can look up user IDs in a few ways including:

**Look up a user's ID by username:**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" "https://api.x.com/2/users/by/username/xdevelopers"
```

**Get your own user ID:**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/users/me
```

Both endpoints return user information including the `id` field, which you can use in subscription filters. Example json response is shown below:

```json theme={null}
{
    "data": {
        "id": "2244994945",
        "name": "Developers",
        "username": "XDevelopers"
    }
}
```

***

## Creating a subscription

Next step is to create a subscription. In this example, we will subscribe to XDevelopers's bio updates. In order to do so, we will pass the `user_id` and `event_type` in the JSON body. In this case, the `event_type` is `profile.update.bio`.

We'll pass X Developer's user ID: `2244994945`, and an optional tag:

```json theme={null}
{
  "event_type": "profile.update.bio",
  "filter": {
    "user_id": "2244994945"
  },
  "tag": "Xdevelopers' bio updates"
}
```

We'll use our [bearer token](https://docs.x.com/fundamentals/authentication/oauth-2-0/overview#bearer-token-also-known-as-app-only) (from the developer portal) for authorization. The app-only bearer token works for public events like this one. Some events are private and require [user-context (OAuth 2.0)](https://docs.x.com/fundamentals/authentication/oauth-2-0/overview#oauth-2-0-authorization-code-flow-with-pkce) authentication instead — see [Event privacy and authentication](/x-api/activity/introduction#event-privacy-and-authentication) for details.

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions \
  -X POST \
  -d '{
    "event_type": "profile.update.bio",
    "filter": {
      "user_id": "2244994945"
    },
    "tag": "Xdevelopers' bio updates"
  }'
```

Upon successful request, your subscription will be created:

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data":[
    {
      "created_at":"2025-10-09T16:35:08.000Z",
      "event_type":"profile.update.bio",
      "filter":{
        "user_id":"2244994945"
      },
      "subscription_id":"1976325569252868096",
      "tag": "Xdevelopers' bio updates",
      "updated_at":"2025-10-09T16:35:08.000Z"
    }
  ],
  "meta": {
    "total_subscriptions": 1
  }
}
```

***

## Getting the events

Once we have created the subscription, we can receive the events via [webhooks](https://docs.x.com/x-api/webhooks/introduction) or a persistent HTTP stream. In this example, we will open the persistent HTTP stream:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/activity/stream
```

When Xdevelopers account updates their profile bio, the event will be delivered through the stream:

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "filter": {
      "user_id": "2244994945"
    },
    "event_type": "profile.update.bio",
    "tag": "Xdevelopers' bio updates",
    "payload": {
      "before": "Mars & Cars",
      "after": "Mars, Cars & AI"
    }
  }
}
```

***

## Subscription management

The X Activity API provides endpoints to manage your subscriptions through standard CRUD operations.

### Create subscription

Create a new subscription to receive events:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X POST \
  https://api.x.com/2/activity/subscriptions \
  -d '{
    "event_type": "profile.update.bio",
    "filter": {
      "user_id": "123456789"
    },
    "tag": "my bio updates",
    "webhook_id": "1976325569252868099"
  }'
```

<Note>
  * The `tag` field is optional. This can be used to help identify events on delivery.
  * The `webhook_id` field is also optional. See our [webhook docs](https://docs.x.com/x-api/webhooks/introduction) for help setting up a webhook. If a `webhook_id` is specified, the event will be delivered to the provided webhook, in addition to the stream if it is open.
</Note>

**Response:**

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "profile.update.bio",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-09T16:35:08.000Z",
    "tag": "my bio updates",
    "webhook_id": "1976325569252868099"
  }
}
```

### List subscriptions

Retrieve all active subscriptions for your application:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions
```

**Response:**

```json title="profile.update.bio" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "subscription_id": "1976325569252868096",
      "event_type": "profile.update.bio",
      "filter": {
        "user_id": "123456789"
      },
      "created_at": "2025-10-09T16:35:08.000Z",
      "updated_at": "2025-10-10T03:50:59.000Z"
    },
    {
      "subscription_id": "1976325569252868097",
      "event_type": "profile.update.profile_picture",
      "filter": {
        "user_id": "987654321"
      },
      "created_at": "2025-10-08T14:35:08.000Z",
      "updated_at": "2025-10-08T14:35:08.000Z"
    }
  ],
  "meta": {
    "total_subscriptions": 2
  }
}
```

### Delete subscription

Remove a subscription:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X DELETE \
  https://api.x.com/2/activity/subscriptions/1976325569252868096
```

**Response:**

```json theme={null}
{
  "data": {
    "deleted": true
  },
  "meta": {
    "total_subscriptions": 0
  }
}
```

`total_subscriptions` shows the remaining number of subscriptions associated with your app after the delete operation.

### Update subscription

The PUT endpoint allows you to update a subscription's delivery method or tag.

Updating the `filter` or `event_type` requires deleting the existing subscription and adding a new one.

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X PUT \
  https://api.x.com/2/activity/subscriptions/1976325569252868096 \
  -d '{
    "tag": "my new tag",
    "webhook_id": "192846273860294839"
  }'
```

**Response:**

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "profile.update.bio",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-10T17:10:58.000Z",
    "tag": "my new tag",
    "webhook_id": "192846273860294839"
  },
  "meta": {
    "total_subscriptions": 1
  }
}
```

***

## Next steps

<CardGroup>
  <Card title="Event payloads" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" href="/x-api/activity/event-payloads">
    Sample JSON for each activity event type
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/activity/activity-stream">
    Full endpoint documentation
  </Card>

  <Card title="Webhooks" icon="webhook" href="/x-api/webhooks/introduction">
    Set up webhook delivery
  </Card>
</CardGroup>


# Update X activity subscription
Source: https://docs.x.com/x-api/activity/update-x-activity-subscription

put /2/activity/subscriptions/{subscription_id}
Updates a subscription for an X activity event



# Create draft Article
Source: https://docs.x.com/x-api/articles/create-draft-article

post /2/articles/draft
Creates a new Article draft that can later be published.



# Articles endpoints for long-form Posts on the X API
Source: https://docs.x.com/x-api/articles/introduction

Use the X API v2 Articles endpoints to programmatically create draft long-form Articles with rich text, media, and embedded Posts, then publish them to X.

The Articles endpoints allow developers to create draft Articles and publish them on X programmatically. Articles are long-form posts that support rich text formatting, embedded posts, links, and images.

These endpoints require user-auth authentication via OAuth 1.0a or OAuth 2.0 PKCE with the `tweet.read`, `tweet.write`, and `users.read` scopes.

Currently, the API supports two endpoints:

## Create a draft Article

Developers can create a new draft Article using the `POST https://api.x.com/2/articles/draft` endpoint. The request body contains the article title, the body content as a [DraftJS](https://draftjs.org/docs/api-reference-content-state) content state of text blocks and entities, and optional cover media uploaded via the [media upload endpoints](/x-api/media/introduction).

## Publish an Article

Once a draft is ready, developers can make it publicly visible using the `POST https://api.x.com/2/articles/{article_id}/publish` endpoint, where `article_id` is the ID returned when the draft was created.

## Getting started

To use the endpoints, you need a user access token. For details on generating one, see the [OAuth 2.0 Authorization Code Flow with PKCE](/fundamentals/authentication/oauth-2-0/authorization-code) documentation.

Once you have the access token, you can create a draft Article as shown below:

```bash title="draft" lines wrap icon="terminal" theme={null}
curl --request POST 'https://api.x.com/2/articles/draft' \
  --header 'Authorization: Bearer XXXXX' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "My first Article",
    "content_state": {
      "blocks": [
        {
          "text": "Hello from the Articles API!",
          "type": "unstyled"
        }
      ],
      "entities": []
    }
  }'
```

If the request is successful, you should see the JSON response as shown below:

```json theme={null}
{
  "data": {
    "id": "1146654567674912769",
    "title": "My first Article"
  }
}
```

You can then publish the draft using the returned Article ID:

```bash theme={null}
curl --request POST 'https://api.x.com/2/articles/1146654567674912769/publish' \
  --header 'Authorization: Bearer XXXXX'
```

If the request is successful, the response contains the ID of the post created for the published Article:

```json theme={null}
{
  "data": {
    "post_id": "1346889436626259968"
  }
}
```


# Publish Article
Source: https://docs.x.com/x-api/articles/publish-article

post /2/articles/{article_id}/publish
Publishes a draft Article, making it publicly visible.



# Create Users Bookmark
Source: https://docs.x.com/x-api/bookmarks/create-bookmark

post /2/users/{id}/bookmarks



# Delete Bookmark
Source: https://docs.x.com/x-api/bookmarks/delete-bookmark

delete /2/users/{id}/bookmarks/{tweet_id}
Removes a Post from the authenticated user's Bookmarks by its ID.



# Get Users Bookmark Folders
Source: https://docs.x.com/x-api/bookmarks/get-bookmark-folders

get /2/users/{id}/bookmarks/folders



# Get Users Bookmarks
Source: https://docs.x.com/x-api/bookmarks/get-bookmarks

get /2/users/{id}/bookmarks



# Get Users Bookmarks by Folder ID
Source: https://docs.x.com/x-api/bookmarks/get-bookmarks-by-folder-id

get /2/users/{id}/bookmarks/folders/{folder_id}



# Create a scheduled broadcast
Source: https://docs.x.com/x-api/broadcasts/create-a-scheduled-broadcast

post /2/broadcasts/scheduled
Schedules a one-off or recurring broadcast for the authenticated user. A `source_id` (ingest) is required at create time.



# Delete a scheduled broadcast
Source: https://docs.x.com/x-api/broadcasts/delete-a-scheduled-broadcast

delete /2/broadcasts/scheduled/{id}
Deletes a scheduled broadcast by its alphanumeric UBS broadcast id.



# Get a broadcast
Source: https://docs.x.com/x-api/broadcasts/get-a-broadcast

get /2/broadcasts/{id}
Returns a broadcast owned by the authenticated user.



# Get a scheduled broadcast
Source: https://docs.x.com/x-api/broadcasts/get-a-scheduled-broadcast

get /2/broadcasts/scheduled/{id}
Returns a single scheduled broadcast by its alphanumeric UBS broadcast id.



# Get broadcast chat history
Source: https://docs.x.com/x-api/broadcasts/get-broadcast-chat-history

get /2/broadcasts/{id}/chat
Returns newest-first chat messages for a broadcast owned by the authenticated user.



# Go live on a scheduled broadcast
Source: https://docs.x.com/x-api/broadcasts/go-live-on-a-scheduled-broadcast

post /2/broadcasts/scheduled/{id}/live
Publishes a schedule that was created or updated with `manual_publish: true`. Without that flag the coordinator auto-publishes at start and this call is rejected.



# List broadcasts
Source: https://docs.x.com/x-api/broadcasts/list-broadcasts

get /2/broadcasts
Returns the authenticated user's live-video broadcasts, or selected owned broadcasts when ids are provided.

At most one of `ids`, `max_results` may be provided. At most one of `ids`, `pagination_token` may be provided.



# List scheduled broadcasts
Source: https://docs.x.com/x-api/broadcasts/list-scheduled-broadcasts

get /2/broadcasts/scheduled
Returns scheduled broadcasts owned by the authenticated user.



# Mute a user in a broadcast chat
Source: https://docs.x.com/x-api/broadcasts/mute-a-user-in-a-broadcast-chat

post /2/broadcasts/{id}/chat/mutes
Prevents a user from posting further messages in a running broadcast chat. The authenticated user must own the broadcast.



# Remove a chat message from a live broadcast
Source: https://docs.x.com/x-api/broadcasts/remove-a-chat-message-from-a-live-broadcast

delete /2/broadcasts/{id}/chat/{message_id}
Removes a specific chat message from a running broadcast owned by the authenticated user.



# Send a chat message to a live broadcast
Source: https://docs.x.com/x-api/broadcasts/send-a-chat-message-to-a-live-broadcast

post /2/broadcasts/{id}/chat
Posts a chat message to a running broadcast, attributed to the authenticated user.



# Unmute a user in a broadcast chat
Source: https://docs.x.com/x-api/broadcasts/unmute-a-user-in-a-broadcast-chat

delete /2/broadcasts/{id}/chat/mutes/{user_id}
Allows a muted user to post messages in a running broadcast chat again. The authenticated user must own the broadcast.



# Update a scheduled broadcast
Source: https://docs.x.com/x-api/broadcasts/update-a-scheduled-broadcast

put /2/broadcasts/scheduled/{id}
Fully replaces schedule fields for a broadcast. Path `:id` is the UBS broadcast id; the body must include `scheduled_broadcast_id` and re-send any fields that should be kept.



# Add Conversation Keys
Source: https://docs.x.com/x-api/chat/add-conversation-keys

post /2/chat/conversations/{id}/keys
Adds (initializes or rotates) the encryption keys for a Chat conversation. Call this before sending messages in a new 1:1 conversation, and again with a newer key version to rotate the conversation key. For 1:1 conversations, provide the recipient's user ID as the conversation id; the server constructs the canonical conversation ID from the authenticated user and recipient. The request body must contain the conversation key version and participant keys (the conversation key encrypted for each participant using their public key).



# Add members to a Chat group conversation
Source: https://docs.x.com/x-api/chat/add-members-to-a-chat-group-conversation

post /2/chat/conversations/{id}/members
Adds one or more members to an existing encrypted Chat group conversation, rotating the conversation key.



# Add public key
Source: https://docs.x.com/x-api/chat/add-public-key

post /2/users/{id}/public_keys
Registers a user's public key for X Chat encryption.



# Append Chat Media Upload
Source: https://docs.x.com/x-api/chat/append-chat-media-upload

post /2/chat/media/upload/{id}/append
Appends media data to an XChat upload session.



# Create Chat Group Conversation
Source: https://docs.x.com/x-api/chat/create-chat-group-conversation

post /2/chat/conversations/group
Creates a new encrypted Chat group conversation on behalf of the authenticated user.



# Delete Chat messages
Source: https://docs.x.com/x-api/chat/delete-chat-messages

post /2/chat/conversations/{id}/messages/delete
Deletes one or more messages from a Chat conversation. For 1:1 conversations, provide the recipient's user ID; the server constructs the canonical conversation ID from the authenticated user and recipient. Delete for all removes a message you sent (or, in groups you administer, any message) for every participant; delete for self removes any message only from your own view.



# Download Chat Media
Source: https://docs.x.com/x-api/chat/download-chat-media

get /2/chat/media/{id}/{media_hash_key}
Downloads encrypted media bytes from an XChat conversation. The response body contains raw binary bytes.



# Finalize Chat Media Upload
Source: https://docs.x.com/x-api/chat/finalize-chat-media-upload

post /2/chat/media/upload/{id}/finalize
Finalizes an XChat media upload session.



# Get Chat Conversation
Source: https://docs.x.com/x-api/chat/get-chat-conversation

get /2/chat/conversations/{id}
Returns metadata for a Chat conversation including type, muted status, and group details. Use chat_conversation.fields to select which fields are returned. Use expansions to hydrate member, admin, or participant user objects. Use user.fields to control which profile fields are returned for expanded users.



# Get Chat Conversation Events
Source: https://docs.x.com/x-api/chat/get-chat-conversation-events

get /2/chat/conversations/{id}/events
Retrieves messages and key change events for a specific Chat conversation with pagination support. For 1:1 conversations, provide the recipient's user ID; the server constructs the canonical conversation ID from the authenticated user and recipient.



# Get Chat Conversations
Source: https://docs.x.com/x-api/chat/get-chat-conversations

get /2/chat/conversations
Retrieves a list of Chat conversations for the authenticated user's inbox.



# Get public keys
Source: https://docs.x.com/x-api/chat/get-user-public-keys

get /2/users/{id}/public_keys
Returns a user's registered public keys for X Chat encryption.



# Initialize Chat Group
Source: https://docs.x.com/x-api/chat/initialize-chat-group

post /2/chat/conversations/group/initialize
Initializes a new Chat group conversation and returns a unique conversation ID. Use the returned conversation_id in a subsequent POST /chat/conversations/group call to fully create and configure the group.



# Initialize Chat Media Upload
Source: https://docs.x.com/x-api/chat/initialize-chat-media-upload

post /2/chat/media/upload/initialize
Initializes an XChat media upload session.



# Mark Conversation as Read
Source: https://docs.x.com/x-api/chat/mark-conversation-as-read

post /2/chat/conversations/{id}/read
Marks a specific Chat conversation as read on behalf of the authenticated user. For 1:1 conversations, provide the recipient's user ID; the server constructs the canonical conversation ID from the authenticated user and recipient.



# Send Chat Message
Source: https://docs.x.com/x-api/chat/send-chat-message

post /2/chat/conversations/{id}/messages
Sends an encrypted message to a specific Chat conversation. For 1:1 conversations, provide the recipient's user ID; the server constructs the canonical conversation ID from the authenticated user and recipient.



# Send Typing Indicator
Source: https://docs.x.com/x-api/chat/send-typing-indicator

post /2/chat/conversations/{id}/typing
Sends a typing indicator to a specific Chat conversation on behalf of the authenticated user. For 1:1 conversations, provide the recipient's user ID; the server constructs the canonical conversation ID from the authenticated user and recipient.



# Get Communities by ID
Source: https://docs.x.com/x-api/communities/get-communities-by-id

get /2/communities/{id}



# Get Communities by ID
Source: https://docs.x.com/x-api/communities/get-community-by-id

get /2/communities/{id}



# Communities Lookup
Source: https://docs.x.com/x-api/communities/lookup/introduction

The Communities lookup endpoint lets you retrieve information about X Communities by their ID. Reference for the X API v2 standard tier covering lookup.

The Communities lookup endpoint lets you retrieve information about X Communities by their ID.

## Overview

Communities are public or private groups on X where members can share Posts, discuss topics, and connect around shared interests.

<CardGroup>
  <Card title="By ID" icon="users-rectangle">
    Get details for a specific Community
  </Card>

  <Card title="Search" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834">
    Find Communities by keyword
  </Card>
</CardGroup>

***

## Endpoint

| Method | Endpoint                                                       | Description         |
| :----- | :------------------------------------------------------------- | :------------------ |
| GET    | [`/2/communities/:id`](/x-api/communities/get-community-by-id) | Get Community by ID |

***

## Response fields

| Field          | Description                  |
| :------------- | :--------------------------- |
| `id`           | Community ID                 |
| `name`         | Community name               |
| `description`  | Community description        |
| `created_at`   | Creation date                |
| `member_count` | Number of members            |
| `is_private`   | Whether Community is private |

***

## Example request

```bash theme={null}
curl "https://api.x.com/2/communities/1234567890?\
community.fields=name,description,member_count,created_at" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Search Communities" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/communities/search/introduction">
    Find Communities by keyword
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/communities/get-community-by-id">
    Full endpoint documentation
  </Card>
</CardGroup>


# Search Communities
Source: https://docs.x.com/x-api/communities/search-communities

get /2/communities/search



# Communities Search
Source: https://docs.x.com/x-api/communities/search/introduction

The Communities Search endpoint lets you search for Communities by keyword. Reference for the X API v2 standard tier covering search.

The Communities Search endpoint lets you search for Communities by keyword. Discover Communities around topics of interest.

## Overview

<CardGroup>
  <Card title="Keyword search" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834">
    Search Communities by name and description
  </Card>

  <Card title="Discover" icon="users-rectangle">
    Find Communities to join
  </Card>
</CardGroup>

***

## Endpoint

| Method | Endpoint                                                         | Description            |
| :----- | :--------------------------------------------------------------- | :--------------------- |
| GET    | [`/2/communities/search`](/x-api/communities/search-communities) | Search for Communities |

***

## Parameters

| Parameter          | Description                 |
| :----------------- | :-------------------------- |
| `query`            | Search query (required)     |
| `max_results`      | Results per page (max 100)  |
| `community.fields` | Additional Community fields |

***

## Example request

```bash theme={null}
curl "https://api.x.com/2/communities/search?\
query=Python&\
max_results=10&\
community.fields=name,description,member_count" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Communities lookup" icon="users-rectangle" href="/x-api/communities/lookup/introduction">
    Look up Communities by ID
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/communities/search-communities">
    Full endpoint documentation
  </Card>
</CardGroup>


# Create Community Notes
Source: https://docs.x.com/x-api/community-notes/create-a-community-note

post /2/notes



# Create Community Notes
Source: https://docs.x.com/x-api/community-notes/create-community-notes

post /2/notes



# Delete a Community Note
Source: https://docs.x.com/x-api/community-notes/delete-a-community-note

delete /2/notes/{id}
Deletes a community note.



# Evaluate a community note
Source: https://docs.x.com/x-api/community-notes/evaluate-a-community-note

post /2/evaluate_note



# Evaluate Community Notes
Source: https://docs.x.com/x-api/community-notes/evaluate-community-notes

post /2/notes/evaluate



# Community Notes API for X API v2
Source: https://docs.x.com/x-api/community-notes/introduction

Overview of the X API v2 Community Notes endpoints for searching eligible Posts and programmatically submitting Community Note proposals from your app.

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.

Currently, the API supports two endpoint categories:

## Search

### Search for X Posts that are eligible to receive a Community Note

Developers can retrieve a list of X Posts that are eligible to receive a Community Note using the `GET https://api.x.com/2/notes/search/posts_eligible_for_notes` endpoint.

### Search for Community Notes that have been written by the user on X Posts

Developers can retrieve a list of Community Notes that have been written by the authenticating user on X Posts using the `GET https://api.x.com/2/notes/search/notes_written` endpoint.

## Evaluate drafted Community Notes before submitting

Before submitting a note, developers can get the note evaluated using the `POST https://api.x.com/2/evaluate_note` endpoint.

## Manage Community Notes

Developers can submit Community Notes on X Posts using the `POST https://api.x.com/2/notes` endpoint.

## Rate limits

The current rate limits are 90 requests per 15 minutes for all Community Notes endpoints and an additional 250 requests per day limit for the Manage Community Notes endpoint.

**Note:** These endpoints are currently in a pilot test. Please check out our [Quick Start Guide](https://docs.x.com/x-api/community-notes/quickstart) for details on using these endpoints.


# Community Notes API quickstart for X API v2
Source: https://docs.x.com/x-api/community-notes/quickstart

X API v2 quickstart for the Community Notes API: authenticate, search eligible Posts, and submit proposed notes as an AI Note Writer step by step.

This guide walks you through using the Community Notes API to search for eligible Posts and submit notes.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Enrollment as a [Community Notes AI Note Writer](https://communitynotes.x.com/guide/en/api/overview)
  * User Access Token (OAuth 1.0a)
</Note>

<Warning>
  Currently, `test_mode` must be set to `true` for all requests. Test notes are not publicly visible.
</Warning>

***

## Find Posts eligible for notes

<Steps>
  <Step title="Search for eligible Posts" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834">
    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        curl "https://api.x.com/2/notes/search/posts_eligible_for_notes?\
        test_mode=true&\
        max_results=100" \
          -H "Authorization: OAuth ..."
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        from requests_oauthlib import OAuth1Session
        import json

        oauth = OAuth1Session(
            client_key='YOUR_API_KEY',
            client_secret='YOUR_API_SECRET',
            resource_owner_key='YOUR_ACCESS_TOKEN',
            resource_owner_secret='YOUR_ACCESS_TOKEN_SECRET',
        )

        url = "https://api.x.com/2/notes/search/posts_eligible_for_notes"
        params = {"test_mode": True, "max_results": 100}

        response = oauth.get(url, params=params)
        print(json.dumps(response.json(), indent=2))
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Review eligible Posts" icon="eye">
    ```json theme={null}
    {
      "data": [
        {
          "id": "1933207126262096118",
          "text": "Join us to learn more about our new analytics endpoints...",
          "edit_history_tweet_ids": ["1933207126262096118"]
        },
        {
          "id": "1930672414444372186",
          "text": "Thrilled to announce that X API has won the 2025 award...",
          "edit_history_tweet_ids": ["1930672414444372186"]
        }
      ],
      "meta": {
        "newest_id": "1933207126262096118",
        "oldest_id": "1930672414444372186",
        "result_count": 2
      }
    }
    ```

    Use the Post `id` from the response to write a Community Note.
  </Step>
</Steps>

***

## Submit a Community Note

<Steps>
  <Step title="Prepare your note" icon="pen">
    A Community Note requires:

    * `post_id` — The Post you're adding context to
    * `text` — Your note (1-280 characters, must include a source URL)
    * `classification` — Either `misinformed_or_potentially_misleading` or `not_misleading`
    * `misleading_tags` — Required if classification is misleading
    * `trustworthy_sources` — Boolean indicating if source is trustworthy
  </Step>

  <Step title="Submit the note" icon="paper-plane">
    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        curl -X POST "https://api.x.com/2/notes" \
          -H "Authorization: OAuth ..." \
          -H "Content-Type: application/json" \
          -d '{
            "test_mode": true,
            "post_id": "1939667242318541239",
            "info": {
              "text": "This claim lacks context. See the full report: https://example.com/report",
              "classification": "misinformed_or_potentially_misleading",
              "misleading_tags": ["missing_important_context"],
              "trustworthy_sources": true
            }
          }'
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        from requests_oauthlib import OAuth1Session
        import json

        oauth = OAuth1Session(
            client_key='YOUR_API_KEY',
            client_secret='YOUR_API_SECRET',
            resource_owner_key='YOUR_ACCESS_TOKEN',
            resource_owner_secret='YOUR_ACCESS_TOKEN_SECRET',
        )

        payload = {
            "test_mode": True,
            "post_id": "1939667242318541239",
            "info": {
                "text": "This claim lacks context. See the full report: https://example.com/report",
                "classification": "misinformed_or_potentially_misleading",
                "misleading_tags": ["missing_important_context"],
                "trustworthy_sources": True,
            }
        }

        response = oauth.post("https://api.x.com/2/notes", json=payload)
        print(json.dumps(response.json(), indent=2))
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Receive confirmation" icon="check">
    ```json theme={null}
    {
      "data": {
        "note_id": "1938678124100886981"
      }
    }
    ```
  </Step>
</Steps>

***

## Get your submitted notes

Retrieve notes you've written:

```python title="Example" lines wrap icon="python" theme={null}
from requests_oauthlib import OAuth1Session
import json

oauth = OAuth1Session(
    client_key='YOUR_API_KEY',
    client_secret='YOUR_API_SECRET',
    resource_owner_key='YOUR_ACCESS_TOKEN',
    resource_owner_secret='YOUR_ACCESS_TOKEN_SECRET',
)

url = "https://api.x.com/2/notes/search/notes_written"
params = {"test_mode": True, "max_results": 100}

response = oauth.get(url, params=params)
print(json.dumps(response.json(), indent=2))
```

**Response:**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "1939827717186494817",
      "info": {
        "text": "This claim lacks context. https://example.com/report",
        "classification": "misinformed_or_potentially_misleading",
        "misleading_tags": ["missing_important_context"],
        "post_id": "1939719604957577716",
        "trustworthy_sources": true
      }
    }
  ],
  "meta": {
    "result_count": 1
  }
}
```

***

## Classification options

<AccordionGroup>
  <Accordion title="Misleading tags">
    When classification is `misinformed_or_potentially_misleading`, include one or more tags:

    | Tag                         | Description                      |
    | :-------------------------- | :------------------------------- |
    | `disputed_claim_as_fact`    | Presents disputed claim as fact  |
    | `factual_error`             | Contains factual errors          |
    | `manipulated_media`         | Media has been altered           |
    | `misinterpreted_satire`     | Satire taken out of context      |
    | `missing_important_context` | Lacks key context                |
    | `outdated_information`      | Information is no longer current |
    | `other`                     | Other reasons                    |
  </Accordion>

  <Accordion title="Not misleading">
    When classification is `not_misleading`, no misleading tags are required.
  </Accordion>
</AccordionGroup>

***

## Common errors

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    ```json theme={null}
    {"title": "Unauthorized", "status": 401, "detail": "Unauthorized"}
    ```

    **Resolution:** Check your OAuth credentials are correct.
  </Accordion>

  <Accordion title="403 Forbidden">
    ```json theme={null}
    {"detail": "User must be an API Note Writer to access this endpoint."}
    ```

    **Resolution:** Enroll as a [Community Notes AI Note Writer](https://communitynotes.x.com/guide/en/api/overview).
  </Accordion>

  <Accordion title="Duplicate note error">
    ```json theme={null}
    {"message": "User already created a note for this post."}
    ```

    **Resolution:** You can only submit one note per Post.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup>
  <Card title="Community Notes Guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="https://communitynotes.x.com/guide/en/api/overview">
    Official Community Notes documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# Search Community Notes Written
Source: https://docs.x.com/x-api/community-notes/search-community-notes-written

get /2/notes/search/notes_written



# Search Eligible Posts
Source: https://docs.x.com/x-api/community-notes/search-eligible-posts

get /2/notes/search/posts_eligible_for_notes



# Search Community Notes Written
Source: https://docs.x.com/x-api/community-notes/search-for-community-notes-written

get /2/notes/search/notes_written



# Search Eligible Posts
Source: https://docs.x.com/x-api/community-notes/search-for-posts-eligible-for-community-notes

get /2/notes/search/posts_eligible_for_notes



# Integration guide
Source: https://docs.x.com/x-api/compliance/batch-compliance/integrate

When using the Batch compliance endpoints, developers can batch upload large amounts of. Reference for the X API v2 standard tier covering batch compliance.

## 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",
  
```


# Batch Compliance
Source: https://docs.x.com/x-api/compliance/batch-compliance/introduction

Use the X API v2 Batch Compliance endpoints to upload Post ID or user ID datasets and retrieve current compliance status for deletions, suspensions, and edits.

The Batch Compliance endpoints let you upload datasets of Post IDs or user IDs and receive their current compliance status. Use this to identify deleted Posts, suspended accounts, and other compliance events.

## Overview

<CardGroup>
  <Card title="Post compliance" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f">
    Check status of Posts in bulk
  </Card>

  <Card title="User compliance" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305">
    Check status of users in bulk
  </Card>

  <Card title="Asynchronous" icon="clock">
    Submit jobs and retrieve results later
  </Card>

  <Card title="Large datasets" icon="database">
    Process millions of IDs
  </Card>
</CardGroup>

***

## How it works

1. **Create a job** — Specify the type (Posts or users) and upload URL
2. **Upload IDs** — Upload your dataset to the provided URL
3. **Wait for processing** — Job processes asynchronously
4. **Download results** — Get compliance status for each ID

***

## Endpoints

| Method | Endpoint                                                               | Description                 |
| :----- | :--------------------------------------------------------------------- | :-------------------------- |
| POST   | [`/2/compliance/jobs`](/x-api/compliance/create-compliance-job)        | Create a new compliance job |
| GET    | [`/2/compliance/jobs/:id`](/x-api/compliance/get-compliance-job-by-id) | Get job status              |
| GET    | [`/2/compliance/jobs`](/x-api/compliance/get-compliance-jobs)          | List all jobs               |

***

## Job types

| Type     | Description                  |
| :------- | :--------------------------- |
| `tweets` | Check Post compliance status |
| `users`  | Check user compliance status |

***

## Compliance events

### Post events

| Event       | Description                  |
| :---------- | :--------------------------- |
| `deleted`   | Post was deleted by user     |
| `bounced`   | Post failed compliance check |
| `protected` | Account became protected     |
| `suspended` | Account was suspended        |
| `scrub_geo` | Geo data was removed         |

### User events

| Event         | Description              |
| :------------ | :----------------------- |
| `deleted`     | Account was deleted      |
| `suspended`   | Account was suspended    |
| `protected`   | Account became protected |
| `deactivated` | Account was deactivated  |

***

## Example: Create a job

```bash theme={null}
curl -X POST "https://api.x.com/2/compliance/jobs" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tweets",
    "name": "my-compliance-job"
  }'
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [Bearer Token](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/compliance/batch-compliance/quickstart">
    Create your first compliance job
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/compliance/batch-compliance/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/compliance/create-compliance-job">
    Full endpoint documentation
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.x.com/x-api/compliance/batch-compliance/quickstart

This guide walks you through creating a batch compliance job to check the compliance. Reference for the X API v2 standard tier covering batch compliance.

This guide walks you through creating a batch compliance job to check the compliance status of Posts or users.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token
</Note>

***

<Steps>
  <Step title="Create a job" icon="plus">
    Create a new compliance job specifying the type (tweets or users):

    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        curl -X POST "https://api.x.com/2/compliance/jobs" \
          -H "Authorization: Bearer $BEARER_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "type": "tweets",
            "name": "my-compliance-job"
          }'
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        import requests

        bearer_token = "YOUR_BEARER_TOKEN"

        url = "https://api.x.com/2/compliance/jobs"
        headers = {
            "Authorization": f"Bearer {bearer_token}",
            "Content-Type": "application/json"
        }
        payload = {
            "type": "tweets",
            "name": "my-compliance-job"
        }

        response = requests.post(url, headers=headers, json=payload)
        print(response.json())
        ```
      </Tab>
    </Tabs>

    **Response:**

    ```json theme={null}
    {
      "data": {
        "id": "1234567890",
        "type": "tweets",
        "name": "my-compliance-job",
        "status": "created",
        "upload_url": "https://storage.googleapis.com/...",
        "download_url": "https://storage.googleapis.com/...",
        "created_at": "2024-01-15T10:00:00.000Z"
      }
    }
    ```

    Save the `upload_url` and `download_url` for the next steps.
  </Step>

  <Step title="Prepare your data file" icon="file">
    Create a text file with one ID per line:

    ```
    1234567890
    1234567891
    1234567892
    1234567893
    ```

    Save as `ids.txt`.
  </Step>

  <Step title="Upload your data" icon="upload">
    Upload the file to the provided `upload_url`:

    ```bash theme={null}
    curl -X PUT "UPLOAD_URL_FROM_RESPONSE" \
      -H "Content-Type: text/plain" \
      --data-binary @ids.txt
    ```
  </Step>

  <Step title="Check job status" icon="clock">
    Poll the job status until it's complete:

    ```bash theme={null}
    curl "https://api.x.com/2/compliance/jobs/1234567890" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```

    **Job statuses:**

    | Status        | Description                   |
    | :------------ | :---------------------------- |
    | `created`     | Job created, awaiting upload  |
    | `in_progress` | Processing data               |
    | `complete`    | Results ready for download    |
    | `failed`      | Job failed                    |
    | `expired`     | Job expired before completion |
  </Step>

  <Step title="Download results" icon="download">
    Once status is `complete`, download from the `download_url`:

    ```bash theme={null}
    curl "DOWNLOAD_URL_FROM_RESPONSE" -o results.json
    ```

    **Result format** (one JSON object per line):

    ```json theme={null}
    {"id": "1234567890", "action": "delete", "created_at": "2024-01-10T12:00:00.000Z", "redacted_at": "2024-01-12T08:30:00.000Z", "reason": "deleted"}
    {"id": "1234567891", "action": "delete", "created_at": "2024-01-10T12:00:00.000Z", "redacted_at": "2024-01-13T14:20:00.000Z", "reason": "suspended"}
    ```

    Only IDs with compliance events appear in the results. IDs not in the results are still valid.
  </Step>
</Steps>

***

## Compliance actions

<AccordionGroup>
  <Accordion title="Post compliance events">
    | Action   | Reason      | Description                  |
    | :------- | :---------- | :--------------------------- |
    | `delete` | `deleted`   | Post was deleted             |
    | `delete` | `bounced`   | Post failed compliance check |
    | `delete` | `protected` | Account became protected     |
    | `delete` | `suspended` | Account was suspended        |
    | `delete` | `scrub_geo` | Geo data was removed         |
  </Accordion>

  <Accordion title="User compliance events">
    | Action   | Reason        | Description              |
    | :------- | :------------ | :----------------------- |
    | `delete` | `deleted`     | Account was deleted      |
    | `delete` | `suspended`   | Account was suspended    |
    | `delete` | `protected`   | Account became protected |
    | `delete` | `deactivated` | Account was deactivated  |
  </Accordion>
</AccordionGroup>

***

## List all jobs

Get all compliance jobs for your App:

```bash theme={null}
curl "https://api.x.com/2/compliance/jobs?type=tweets" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

***

## Next steps

<CardGroup>
  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/compliance/batch-compliance/integrate">
    Key concepts and best practices
  </Card>

  <Card title="Compliance streams" icon="stream" href="/x-api/compliance/streams/introduction">
    Real-time compliance events
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/compliance/create-compliance-job">
    Full endpoint documentation
  </Card>
</CardGroup>


# Create Compliance Job
Source: https://docs.x.com/x-api/compliance/create-compliance-job

post /2/compliance/jobs
Creates a new Compliance Job for the specified job type.



# Get Compliance Job by ID
Source: https://docs.x.com/x-api/compliance/get-compliance-job-by-id

get /2/compliance/jobs/{id}
Retrieves details of a specific Compliance Job by its ID.



# Get Compliance Jobs
Source: https://docs.x.com/x-api/compliance/get-compliance-jobs

get /2/compliance/jobs
Retrieves a list of Compliance Jobs filtered by job type and optional status.



# Compliance event streams on the X API v2
Source: https://docs.x.com/x-api/compliance/streams/introduction

Use X API v2 compliance event streams to keep stored X data in sync with Post deletes, edits, and account changes for users in near real time.

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\_edit** - 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).

<div>
  <Button href="https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80">
    Run in Postman
  </Button>

  <Button href="https://developer.x.com/apitools/api?endpoint=/2/compliance/jobs">
    Try with API Explorer
  </Button>
</div>

***

## Streaming fundamentals

<CardGroup>
  <Card title="Consuming streaming data" icon="stream" href="/x-api/fundamentals/consuming-streaming-data">
    Best practices for streaming clients
  </Card>

  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Reconnect gracefully
  </Card>

  <Card title="High volume capacity" icon="gauge-high" href="/x-api/fundamentals/high-volume-capacity">
    Handle high throughput
  </Card>

  <Card title="Recovery and redundancy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055" href="/x-api/fundamentals/recovery-and-redundancy">
    Build resilient applications
  </Card>
</CardGroup>


# Get Connection History
Source: https://docs.x.com/x-api/connections/get-connection-history

get /2/connections
Returns active and historical streaming connections with disconnect reasons for the authenticated application.



# Stream Connections
Source: https://docs.x.com/x-api/connections/introduction

The Stream Connections endpoints let you retrieve the history of your application's streaming. Reference for the X API v2 standard tier covering connections.

The Stream Connections endpoints let you retrieve the history of your application's streaming connections and terminate active or multiple connections. Use these to monitor connection status, resolve issues like duplicate connections, and manage streaming sessions for endpoints like Filtered Stream and Sampled Stream.

<Note>
  These endpoints require [Bearer Token authentication](/fundamentals/authentication/oauth-2-0/application-only) and are available for apps with access to streaming endpoints.
</Note>

## Overview

<CardGroup>
  <Card title="Connection history" icon="history">
    View active and past connections
  </Card>

  <Card title="Terminate all" icon="power-off">
    End all active streaming connections
  </Card>

  <Card title="Terminate by endpoint" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e">
    Stop connections for specific streams
  </Card>

  <Card title="Terminate multiple" icon="list-check">
    Kill specific connections by UUID
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                                                               | Description                                     |
| :----- | :------------------------------------------------------------------------------------- | :---------------------------------------------- |
| GET    | [`/2/connections`](/x-api/connections/get-connection-history)                          | Get active and historical streaming connections |
| DELETE | [`/2/connections/all`](/x-api/connections/terminate-all-connections)                   | Terminate all active connections                |
| DELETE | [`/2/connections/{endpoint_id}`](/x-api/connections/terminate-connections-by-endpoint) | Terminate connections for a specific endpoint   |
| DELETE | [`/2/connections`](/x-api/connections/terminate-multiple-connections)                  | Terminate multiple connections by UUIDs         |

***

## Use cases

* **Troubleshoot disconnections** — Check history to diagnose issues ([see handling disconnections](/x-api/fundamentals/handling-disconnections))
* **Enforce connection limits** — Terminate duplicate or excess connections
* **Clean up sessions** — Stop all streams before maintenance or redeploy
* **Monitor usage** — Track connection patterns across endpoints like filtered\_stream, sample\_stream

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/fundamentals/developer-apps) in the Developer Console with streaming access
  * Your App's [Bearer Token](/fundamentals/authentication/oauth-2-0/application-only)
</Note>

<CardGroup>
  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/connections/get-connection-history">
    Full endpoint documentation
  </Card>

  <Card title="Streaming fundamentals" icon="stream" href="/x-api/fundamentals/consuming-streaming-data">
    Learn about streaming
  </Card>
</CardGroup>


# Terminate all connections
Source: https://docs.x.com/x-api/connections/terminate-all-connections

delete /2/connections/all
Terminates all active streaming connections for the authenticated application.



# Terminate connections by endpoint
Source: https://docs.x.com/x-api/connections/terminate-connections-by-endpoint

delete /2/connections/{endpoint_id}
Terminates all streaming connections for a specific endpoint ID for the authenticated application.



# Terminate multiple connections
Source: https://docs.x.com/x-api/connections/terminate-multiple-connections

delete /2/connections
Terminates multiple streaming connections by their UUIDs for the authenticated application.



# Manage Direct Message blocks on the X API v2
Source: https://docs.x.com/x-api/direct-messages/blocks/introduction

Use the X API v2 Manage DM blocks endpoints to block or unblock a specified account on behalf of an authenticated user and control who can send Direct 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:

```json theme={null}
{
   "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:

```json theme={null}
{
   "data": {
       "blocked": false
   }
}
```


# Create Direct Messages by Conversation ID
Source: https://docs.x.com/x-api/direct-messages/create-direct-messages-by-conversation-id

post /2/dm_conversations/{dm_conversation_id}/messages



# Create DM conversation
Source: https://docs.x.com/x-api/direct-messages/create-dm-conversation

post /2/dm_conversations
Initiates a new direct message conversation with specified participants.



# Create Direct Messages by Conversation ID
Source: https://docs.x.com/x-api/direct-messages/create-dm-message-by-conversation-id

post /2/dm_conversations/{dm_conversation_id}/messages



# Create DM message by participant ID
Source: https://docs.x.com/x-api/direct-messages/create-dm-message-by-participant-id

post /2/dm_conversations/with/{participant_id}/messages
Sends a new direct message to a specific participant by their ID.



# Delete DM event
Source: https://docs.x.com/x-api/direct-messages/delete-dm-event

delete /2/dm_events/{event_id}
Deletes a specific direct message event by its ID, if owned by the authenticated user.



# Download DM Media
Source: https://docs.x.com/x-api/direct-messages/download-dm-media

get /2/dm_conversations/media/{dm_id}/{media_id}/{resource_id}
Downloads media attached to a legacy Direct Message. The requesting user must be a participant in the conversation containing the specified DM event. The response body contains raw binary bytes.



# Get Direct Messages Events
Source: https://docs.x.com/x-api/direct-messages/get-direct-messages-events

get /2/dm_events



# Get Direct Messages Events by Conversation ID
Source: https://docs.x.com/x-api/direct-messages/get-direct-messages-events-by-conversation-id

get /2/dm_conversations/{id}/dm_events



# Get Direct Messages Events by ID
Source: https://docs.x.com/x-api/direct-messages/get-direct-messages-events-by-id

get /2/dm_events/{event_id}



# Get Direct Messages Events by Participant ID
Source: https://docs.x.com/x-api/direct-messages/get-direct-messages-events-by-participant-id

get /2/dm_conversations/with/{participant_id}/dm_events



# Get Direct Messages Events by ID
Source: https://docs.x.com/x-api/direct-messages/get-dm-event-by-id

get /2/dm_events/{event_id}



# Get Direct Messages Events
Source: https://docs.x.com/x-api/direct-messages/get-dm-events

get /2/dm_events



# Get Direct Messages Events by Participant ID
Source: https://docs.x.com/x-api/direct-messages/get-dm-events-for-a-dm-conversation

get /2/dm_conversations/with/{participant_id}/dm_events



# Get Direct Messages Events by Conversation ID
Source: https://docs.x.com/x-api/direct-messages/get-dm-events-for-a-dm-conversation-1

get /2/dm_conversations/{id}/dm_events



# Integration Guide
Source: https://docs.x.com/x-api/direct-messages/lookup/integrate

This guide covers the key concepts you need to integrate the Direct Messages lookup endpoints into. Reference for the X API v2 standard tier covering lookup.

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 |

<Warning>
  App-Only authentication is not supported. All Direct Messages are private.
</Warning>

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

<CardGroup>
  <Card title="One-to-one" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f">
    Always has exactly two participants. Conversation ID format: `{smaller_user_id}-{larger_user_id}`
  </Card>

  <Card title="Group" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=ce6313d8c0b7b4e5363f2ce80b89f7e4">
    Two or more participants. Membership can change over time.
  </Card>
</CardGroup>

***

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

<AccordionGroup>
  <Accordion title="MessageCreate">
    ```json theme={null}
    {
      "id": "1582838499983564806",
      "event_type": "MessageCreate",
      "text": "Hi everyone.",
      "sender_id": "944480690",
      "dm_conversation_id": "1578398451921985538",
      "created_at": "2022-10-19T20:58:00.000Z"
    }
    ```
  </Accordion>

  <Accordion title="ParticipantsJoin">
    ```json theme={null}
    {
      "id": "1582835469712138240",
      "event_type": "ParticipantsJoin",
      "participant_ids": ["944480690"],
      "sender_id": "17200003",
      "dm_conversation_id": "1578398451921985538",
      "created_at": "2022-10-19T20:45:58.000Z"
    }
    ```
  </Accordion>

  <Accordion title="ParticipantsLeave">
    ```json theme={null}
    {
      "id": "1582838535115067392",
      "event_type": "ParticipantsLeave",
      "participant_ids": ["944480690"],
      "dm_conversation_id": "1578398451921985538",
      "created_at": "2022-10-19T20:58:09.000Z"
    }
    ```
  </Accordion>
</AccordionGroup>

***

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

<CodeGroup>
  ```bash cURL theme={null}
  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 title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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}`);
    });
  }
  ```
</CodeGroup>

***

## Pagination

DM events are returned in reverse chronological order (newest first):

<CodeGroup>
  ```bash cURL theme={null}
  # 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 title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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`);
  ```
</CodeGroup>

<Note>
  Events from up to **30 days ago** are available.
</Note>

***

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

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/direct-messages/lookup/quickstart">
    Make your first DM lookup request
  </Card>

  <Card title="Send DMs" icon="paper-plane" href="/x-api/direct-messages/manage/introduction">
    Send Direct Messages
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/direct-messages/get-dm-events">
    Full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# Direct Messages Lookup
Source: https://docs.x.com/x-api/direct-messages/lookup/introduction

The Direct Messages lookup endpoints let you retrieve DM events for the authenticated user. Reference for the X API v2 standard tier covering lookup.

The Direct Messages lookup endpoints let you retrieve DM events for the authenticated user, including messages from both one-to-one and group conversations.

## Overview

<CardGroup>
  <Card title="All DM events" icon="messages">
    Get all DM events for the user
  </Card>

  <Card title="One-to-one" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f">
    Get events from a specific conversation
  </Card>

  <Card title="By conversation ID" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=ce6313d8c0b7b4e5363f2ce80b89f7e4">
    Get events by conversation ID
  </Card>

  <Card title="Event types" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bell.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=5e0b3dcfbb39ba3d4619931d7cd927d1">
    Messages, joins, and leaves
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                                                                                            | Description                             |
| :----- | :------------------------------------------------------------------------------------------------------------------ | :-------------------------------------- |
| GET    | [`/2/dm_events`](/x-api/direct-messages/get-dm-events)                                                              | Get all DM events for the user          |
| GET    | [`/2/dm_conversations/with/:participant_id/dm_events`](/x-api/direct-messages/get-dm-events-for-a-dm-conversation)  | Get events from one-to-one conversation |
| GET    | [`/2/dm_conversations/:dm_conversation_id/dm_events`](/x-api/direct-messages/get-dm-events-for-a-dm-conversation-1) | Get events by conversation ID           |

***

## Event types

| Event               | Description                            |
| :------------------ | :------------------------------------- |
| `MessageCreate`     | A message was sent in the conversation |
| `ParticipantsJoin`  | A user joined the conversation         |
| `ParticipantsLeave` | A user left the conversation           |

***

## Data retention

<Note>
  Events from up to **30 days ago** are available through these endpoints.
</Note>

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * User Access Tokens via [3-legged OAuth](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/direct-messages/lookup/quickstart">
    Make your first DM lookup request
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/direct-messages/lookup/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/direct-messages/get-dm-events">
    Full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# Migration guide
Source: https://docs.x.com/x-api/direct-messages/lookup/migrate

Guide to migrating Direct Message lookup code from X API v1.1 to v2, covering endpoint changes, request parameters, and new response payloads.

## 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)                         | [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)<br /><br />Direct Messages conversations are introduced as a fundamental API object.   <br /><br />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<br /><br />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)\*  <br />\*All requests require user tokens                                                                  |                                                                | GET requests: 300 requests per 15 mins<br /><br />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 <br /><br />/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  <br />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  <br />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  <br />  <br />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  <br />Rate limit is applied across all three GET endpoints |


# Quickstart
Source: https://docs.x.com/x-api/direct-messages/lookup/quickstart

This guide walks you through retrieving Direct Message events for the authenticated user. Reference for the X API v2 standard tier covering lookup.

This guide walks you through retrieving Direct Message events for the authenticated user.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Get all DM events

Retrieve all DM events for the authenticated user:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/dm_events?\
  dm_event.fields=created_at,sender_id,text&\
  max_results=100" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get all DM events with pagination
  for page in client.dm_events.list(
      dm_event_fields=["created_at", "sender_id", "text"],
      max_results=100
  ):
      for event in page.data:
          print(f"{event.event_type}: {event.text}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get all DM events with pagination
  const paginator = client.dmEvents.list({
    dmEventFields: ["created_at", "sender_id", "text"],
    maxResults: 100,
  });

  for await (const page of paginator) {
    page.data?.forEach((event) => {
      console.log(`${event.event_type}: ${event.text}`);
    });
  }
  ```
</CodeGroup>

### Response

```json title="MessageCreate" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "1234567890",
      "event_type": "MessageCreate",
      "text": "Hello! How are you?",
      "sender_id": "9876543210",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "result_count": 1,
    "next_token": "abc123"
  }
}
```

***

## Get one-to-one conversation

Retrieve DM events from a specific one-to-one conversation:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/dm_conversations/with/9876543210/dm_events?\
  dm_event.fields=created_at,sender_id,text" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get DM events from a one-to-one conversation
  for page in client.dm_events.get_by_participant(
      participant_id="9876543210",
      dm_event_fields=["created_at", "sender_id", "text"]
  ):
      for event in page.data:
          print(f"{event.created_at}: {event.text}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get DM events from a one-to-one conversation
  const paginator = client.dmEvents.getByParticipant("9876543210", {
    dmEventFields: ["created_at", "sender_id", "text"],
  });

  for await (const page of paginator) {
    page.data?.forEach((event) => {
      console.log(`${event.created_at}: ${event.text}`);
    });
  }
  ```
</CodeGroup>

Replace `9876543210` with the other participant's user ID.

***

## Get conversation by ID

Retrieve DM events from a specific conversation ID:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/dm_conversations/1234567890-9876543210/dm_events?\
  dm_event.fields=created_at,sender_id,text" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get DM events from a conversation by ID
  for page in client.dm_events.get_by_conversation(
      dm_conversation_id="1234567890-9876543210",
      dm_event_fields=["created_at", "sender_id", "text"]
  ):
      for event in page.data:
          print(f"{event.created_at}: {event.text}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get DM events from a conversation by ID
  const paginator = client.dmEvents.getByConversation("1234567890-9876543210", {
    dmEventFields: ["created_at", "sender_id", "text"],
  });

  for await (const page of paginator) {
    page.data?.forEach((event) => {
      console.log(`${event.created_at}: ${event.text}`);
    });
  }
  ```
</CodeGroup>

***

## Filter by event type

Get only specific event types:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/dm_events?\
  event_types=MessageCreate&\
  dm_event.fields=created_at,sender_id,text" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get only MessageCreate events
  for page in client.dm_events.list(
      event_types=["MessageCreate"],
      dm_event_fields=["created_at", "sender_id", "text"]
  ):
      for event in page.data:
          print(f"{event.text}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get only MessageCreate events
  const paginator = client.dmEvents.list({
    eventTypes: ["MessageCreate"],
    dmEventFields: ["created_at", "sender_id", "text"],
  });

  for await (const page of paginator) {
    page.data?.forEach((event) => {
      console.log(event.text);
    });
  }
  ```
</CodeGroup>

### Event types

| Type                | Description              |
| :------------------ | :----------------------- |
| `MessageCreate`     | A message was sent       |
| `ParticipantsJoin`  | User joined conversation |
| `ParticipantsLeave` | User left conversation   |

***

## Include user data

Expand sender information:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/dm_events?\
  dm_event.fields=created_at,sender_id,text&\
  expansions=sender_id&\
  user.fields=username,profile_image_url" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get DM events with sender info
  for page in client.dm_events.list(
      dm_event_fields=["created_at", "sender_id", "text"],
      expansions=["sender_id"],
      user_fields=["username", "profile_image_url"]
  ):
      for event in page.data:
          # Match sender from includes
          print(f"{event.sender_id}: {event.text}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get DM events with sender info
  const paginator = client.dmEvents.list({
    dmEventFields: ["created_at", "sender_id", "text"],
    expansions: ["sender_id"],
    userFields: ["username", "profile_image_url"],
  });

  for await (const page of paginator) {
    page.data?.forEach((event) => {
      console.log(`${event.sender_id}: ${event.text}`);
    });
    // Sender user objects are in page.includes.users
  }
  ```
</CodeGroup>

### Response with expansion

```json title="MessageCreate" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "1234567890",
      "event_type": "MessageCreate",
      "text": "Hello!",
      "sender_id": "9876543210"
    }
  ],
  "includes": {
    "users": [
      {
        "id": "9876543210",
        "username": "example_user",
        "profile_image_url": "https://..."
      }
    ]
  }
}
```

***

## Common parameters

| Parameter          | Description                          |
| :----------------- | :----------------------------------- |
| `max_results`      | Events per page (1-100, default 100) |
| `pagination_token` | Token for next page                  |
| `dm_event.fields`  | Event fields to return               |
| `event_types`      | Filter by event type                 |
| `expansions`       | Related objects to include           |

***

## Next steps

<CardGroup>
  <Card title="Send DMs" icon="paper-plane" href="/x-api/direct-messages/manage/quickstart">
    Send Direct Messages
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/direct-messages/lookup/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/direct-messages/get-dm-events">
    Full endpoint documentation
  </Card>
</CardGroup>


# Integration Guide
Source: https://docs.x.com/x-api/direct-messages/manage/integrate

This guide covers the key concepts you need to integrate the manage Direct Messages endpoints into. Reference for the X API v2 standard tier covering manage.

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 |

<Warning>
  App-Only authentication is not supported. All Direct Messages are private.
</Warning>

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

<CodeGroup>
  ```bash cURL theme={null}
  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 theme={null}
  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 theme={null}
  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);
  ```
</CodeGroup>

### Group conversation

Create a new group and send the first message:

<CodeGroup>
  ```bash cURL theme={null}
  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 theme={null}
  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 theme={null}
  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);
  ```
</CodeGroup>

<Note>
  The `conversation_type` field must be set to `"Group"` (case sensitive).
</Note>

### Add to existing conversation

Send a message to any conversation you're part of:

<CodeGroup>
  ```bash cURL theme={null}
  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 theme={null}
  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 theme={null}
  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);
  ```
</CodeGroup>

***

## Media attachments

Attach one piece of media (photo, video, or GIF) per message.

<Steps>
  <Step title="Upload media">
    Use the [Media Upload endpoint](/x-api/media/quickstart/media-upload-chunked) to upload your file and get a `media_id`.
  </Step>

  <Step title="Include in message">
    ```json theme={null}
    {
      "text": "Check out this image!",
      "attachments": [{"media_id": "1583157113245011970"}]
    }
    ```
  </Step>
</Steps>

<Note>
  * The authenticated user must have uploaded the media
  * Media is available for 24 hours after upload
  * Only one attachment per message is supported
</Note>

***

## Sharing posts

Include a Post in your message by adding the Post URL to the text:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Cannot send to user">
    The recipient may have DM settings that prevent messages from unknown users, or may have blocked you.
  </Accordion>

  <Accordion title="Media attachment failed">
    Ensure the media was uploaded by the same authenticated user and is less than 24 hours old.
  </Accordion>

  <Accordion title="Group creation failed">
    Verify all participant IDs are valid and the users allow group DM invites.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/direct-messages/manage/quickstart">
    Send your first Direct Message
  </Card>

  <Card title="DM lookup" icon="inbox" href="/x-api/direct-messages/lookup/introduction">
    Retrieve DM conversations
  </Card>

  <Card title="Media upload" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-photo.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=d0986097dcff55478c32801b20440ecc" href="/x-api/media/quickstart/media-upload-chunked">
    Upload media for attachments
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/direct-messages/create-dm-message-by-participant-id">
    Full endpoint documentation
  </Card>
</CardGroup>


# Manage Direct Messages
Source: https://docs.x.com/x-api/direct-messages/manage/introduction

Use the X API v2 Manage Direct Messages endpoints to create conversations, send new DMs, and delete DM events on behalf of authenticated users on X.

The Manage Direct Messages endpoints let you send and delete Direct Messages on behalf of authenticated users.

## Overview

<CardGroup>
  <Card title="Send message" icon="paper-plane">
    Send a DM to another user
  </Card>

  <Card title="Delete message" icon="trash">
    Delete a DM for yourself
  </Card>

  <Card title="Create conversation" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=ce6313d8c0b7b4e5363f2ce80b89f7e4">
    Start a new conversation
  </Card>

  <Card title="Group messages" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980">
    Send to group conversations
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                            | Description                     |
| :----- | :-------------------------------------------------- | :------------------------------ |
| POST   | `/2/dm_conversations`                               | Create a new conversation       |
| POST   | `/2/dm_conversations/with/:participant_id/messages` | Send to one-to-one conversation |
| POST   | `/2/dm_conversations/:dm_conversation_id/messages`  | Send to existing conversation   |
| DELETE | `/2/dm_events/:id`                                  | Delete a DM event               |

***

## Example: Send a message

```bash theme={null}
curl -X POST "https://api.x.com/2/dm_conversations/with/1234567890/messages" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello! How are you?"}'
```

## Example response

```json theme={null}
{
  "data": {
    "dm_conversation_id": "1234567890-0987654321",
    "dm_event_id": "1122334455667788990"
  }
}
```

***

## Message types

You can send text messages and attach media:

```json theme={null}
{
  "text": "Check out this photo!",
  "attachments": [{
    "media_id": "1234567890123456789"
  }]
}
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * User Access Tokens via [OAuth 2.0 PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/direct-messages/manage/quickstart">
    Send your first DM
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/direct-messages/manage/integrate">
    Key concepts and best practices
  </Card>

  <Card title="DM lookup" icon="messages" href="/x-api/direct-messages/lookup/introduction">
    Retrieve DM events
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/direct-messages/create-dm-message-by-conversation-id">
    Full endpoint documentation
  </Card>
</CardGroup>


# Migration guide
Source: https://docs.x.com/x-api/direct-messages/manage/migrate

Both v1.1 and v2 versions of the Direct Messages endpoints provide methods for creating Direct. Reference for the X API v2 standard tier covering manage.

## 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)                                         | [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)<br /><br />Direct Messages conversations are introduced as a fundamental API object.   <br /><br />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<br /><br />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)\*  <br />\*All requests require user tokens                                                                  | 1000 requests per user per 24 hours  <br />15000 requests per app per 24 hours | 200 requests per 15 minutes per user<br /><br />1000 requests per user per 24 hours<br /><br />15000 requests per app per 24 hours<br /><br />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  <br />15000 requests per app per 24 hours | 200 requests per 15 minutes per user<br /><br />1000 requests per user per 24 hours<br /><br />15000 requests per app per 24 hours<br /><br />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<br /><br />1000 requests per user per 24 hours<br /><br />15000 requests per app per 24 hours<br /><br />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<br /><br />1000 requests per user per 24 hours<br /><br />15000 requests per app per 24 hours<br /><br />These rate limits are shared across all dm\_conversations POST endpoints. |
| Supports group Direct Messages                                 |                   | ✔                                                                                                                                                                                                                       |


# Quickstart
Source: https://docs.x.com/x-api/direct-messages/manage/quickstart

This guide walks you through sending Direct Messages and creating group conversations. Reference for the X API v2 standard tier covering manage.

This guide walks you through sending Direct Messages and creating group conversations.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 2.0 PKCE with `dm.write` and `dm.read` scopes)
</Note>

***

## Send a one-to-one message

<Steps>
  <Step title="Get the recipient's user ID">
    You need the user ID of the person you want to message. You can get this from the [User lookup endpoint](/x-api/users/lookup/introduction).
  </Step>

  <Step title="Send the message">
    <CodeGroup>
      ```bash cURL theme={null}
      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! This is a message from the API."}'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

      # Send a one-to-one message
      response = client.dm.send_message(
          participant_id="9876543210",
          text="Hello! This is a message from the API."
      )

      print(f"Message sent: {response.data.dm_event_id}")
      print(f"Conversation: {response.data.dm_conversation_id}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

      // Send a one-to-one message
      const response = await client.dm.sendMessage({
        participantId: "9876543210",
        text: "Hello! This is a message from the API.",
      });

      console.log(`Message sent: ${response.data?.dm_event_id}`);
      console.log(`Conversation: ${response.data?.dm_conversation_id}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": {
        "dm_conversation_id": "1234567890-9876543210",
        "dm_event_id": "1582103724607971332"
      }
    }
    ```
  </Step>
</Steps>

***

## Create a group conversation

<Steps>
  <Step title="Define participants">
    Gather the user IDs of everyone you want in the group (excluding yourself).
  </Step>

  <Step title="Create the group with first message">
    <CodeGroup>
      ```bash cURL theme={null}
      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 new group!"}
        }'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

      # Create a group conversation
      response = client.dm.create_conversation(
          conversation_type="Group",
          participant_ids=["944480690", "906948460078698496"],
          message={"text": "Welcome to our new group!"}
      )

      print(f"Group created: {response.data.dm_conversation_id}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

      // Create a group conversation
      const response = await client.dm.createConversation({
        conversationType: "Group",
        participantIds: ["944480690", "906948460078698496"],
        message: { text: "Welcome to our new group!" },
      });

      console.log(`Group created: ${response.data?.dm_conversation_id}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Receive the conversation ID">
    ```json theme={null}
    {
      "data": {
        "dm_conversation_id": "1582103724607971328",
        "dm_event_id": "1582103724607971332"
      }
    }
    ```

    Save the `dm_conversation_id` to add more messages later.
  </Step>
</Steps>

***

## Add a message to an existing conversation

Send a message to a conversation you're already part of:

<CodeGroup>
  ```bash cURL theme={null}
  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": "Adding another message to the conversation."}'
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Add message to existing conversation
  response = client.dm.send_message_to_conversation(
      dm_conversation_id="1582103724607971328",
      text="Adding another message to the conversation."
  )

  print(f"Message sent: {response.data.dm_event_id}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Add message to existing conversation
  const response = await client.dm.sendMessageToConversation(
    "1582103724607971328",
    { text: "Adding another message to the conversation." }
  );

  console.log(`Message sent: ${response.data?.dm_event_id}`);
  ```
</CodeGroup>

***

## Send a message with media

<Steps>
  <Step title="Upload the media">
    First, upload your media using the [Media Upload endpoint](/x-api/media/quickstart/media-upload-chunked).
  </Step>

  <Step title="Send with media attachment">
    <CodeGroup>
      ```bash cURL theme={null}
      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": "Check out this image!",
          "attachments": [{"media_id": "1234567890123456789"}]
        }'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

      # Send message with media
      response = client.dm.send_message(
          participant_id="9876543210",
          text="Check out this image!",
          attachments=[{"media_id": "1234567890123456789"}]
      )

      print(f"Message with media sent: {response.data.dm_event_id}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

      // Send message with media
      const response = await client.dm.sendMessage({
        participantId: "9876543210",
        text: "Check out this image!",
        attachments: [{ mediaId: "1234567890123456789" }],
      });

      console.log(`Message with media sent: ${response.data?.dm_event_id}`);
      ```
    </CodeGroup>
  </Step>
</Steps>

***

## Delete a message

Delete a message you sent:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.x.com/2/dm_events/1582103724607971332" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Delete a message
  response = client.dm.delete_message("1582103724607971332")
  print(f"Deleted: {response.data.deleted}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Delete a message
  const response = await client.dm.deleteMessage("1582103724607971332");
  console.log(`Deleted: ${response.data?.deleted}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "deleted": true
  }
}
```

<Warning>
  You can only delete messages you sent, not messages from other participants.
</Warning>

***

## Required scopes

When using OAuth 2.0 PKCE, your access token must have these scopes:

| Scope        | Description                                 |
| :----------- | :------------------------------------------ |
| `dm.write`   | Send and delete messages                    |
| `dm.read`    | Read conversations (required with dm.write) |
| `tweet.read` | Required for some expansions                |
| `users.read` | Required for user expansions                |

***

## Next steps

<CardGroup>
  <Card title="DM lookup" icon="inbox" href="/x-api/direct-messages/lookup/quickstart">
    Retrieve DM conversations
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/direct-messages/manage/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/direct-messages/create-dm-message-by-participant-id">
    Full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# Enterprise
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/enterprise-gnip

Overview of X enterprise APIs and Gnip products, including PowerTrack, Decahose, Search, Engagement, Account Activity, and Compliance Firehose access.

Our enterprise APIs offer the highest level of access and reliability to those who depend on X data. They are designed for teams that 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 self-serve plan isn’t enough to support your needs, you can apply for access to the enterprise products at the following link:

<Button href="https://docs.x.com/forms/enterprise-api-interest">
  Apply for access
</Button>

## Available endpoints

| Category   | Endpoint                                                                         | Description                                                                                                        |
| :--------- | :------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| 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.   |
| Real-time  | [Decahose API](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api)             | Stream a random sample of 10% of all public Posts and their likes.                                                 |
| Real-time  | [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) | Subscribe to users and receive a variety of 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 | [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 on 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 offers an advanced set of operators that are not available with the standard search endpoint. Many of these operators are available to free sandbox users, but you get a more robust set if you use 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 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 to get in contact with our support team.

[Support](https://developer.x.com/en/support/x-api)


# Account Activity API: Enterprise
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/account-activity

Manage webhooks and subscriptions with the enterprise Account Activity API to stream realtime Posts, Direct Messages, likes, follows, and edits.

<Warning>
  The Account Activity API (AAA) is being deprecated. Check out the [X Activity API (XAA)](/x-api/activity/introduction) for real-time user activity delivery going forward.
</Warning>

<Note>
  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.   
</Note>

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)  <br />    <br />\* Post deletes (by user)<br />\* @mentions (of user)<br />\* Replies (to or from user)<br />\* Retweets (by user or of user)<br />\* Quote Tweets (by user or of user)<br />\* Retweets of Quoted Tweets (by user or of user)<br />\* Likes (by user or of user)<br />\* Follows (by user or of user)  <br />    <br />\* Unfollows (by user) | \* Blocks (by user)<br />\* Unblocks (by user)<br />\* Mutes (by user)<br />\* Unmutes (by user)<br />\* Direct Messages sent (by user)<br />\* Direct Messages received (by user)<br />\* Typing indicators (to user)<br />\* Read receipts (to user)<br />\* 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!

<iframe />

### 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](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. 

<Tabs>
  <Tab title="Adding a webhook">
    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** `<URL>` e.g. `https://yourdomain.com/webhooks/twitter/`

    * **Consumer key** `<CONSUMER_KEY>` e.g. `xvz1evFS4wEEPTGEFPHBog`

    * **Access token** `<ACCESS_TOKEN>` e.g.  `370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb`

      ```
      curl --request POST --url 'https://api.x.com/1.1/account_activity/webhooks.json?url=<URL>' --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"'
      ```
  </Tab>

  <Tab title="Viewing a webhook">
    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** `<BEARER_TOKEN>` e.g. `AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...`

      ```curl --request GET --url https://api.x.com/1.1/account_activity/webhooks.json --header 'authorization: Bearer <BEARER_TOKEN>' theme={null}
      ```
  </Tab>

  <Tab title="Removing a webhook">
    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** `<CONSUMER_KEY>` e.g. `xvz1evFS4wEEPTGEFPHBog`

    * **Access token** `<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="<CONSUMER_KEY>", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="<ACCESS_TOKEN>", oauth_version="1.0"' theme={null}
      ```
  </Tab>
</Tabs>

#### 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.

<Tabs>
  <Tab title="Adding a subscription">
    We'll begin with subscribing a user so you receive 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** `<CONSUMER_KEY>` e.g. `xvz1evFS4wEEPTGEFPHBog`

    * **Subscribing user's access token** `<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="<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"'
      ```
  </Tab>

  <Tab title="Viewing subscriptions">
    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** `<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 <BEARER_TOKEN>'
      ```
  </Tab>

  <Tab title="Removing a subscription">
    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** `<CONSUMER_KEY>` e.g. `xvz1evFS4wEEPTGEFPHBog`

    * **Subscribing user's access token** `<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"'
      ```
  </Tab>
</Tabs>

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 abo


# Data dictionary: Enterprise
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary

Reference of every Post, User, and Space field returned by the Enterprise Gnip 2.0 data products, including Native Enriched and Activity Streams.

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

<iframe title="X Post" />

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 title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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 available 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 entities 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:<br /><br />"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:<br /><br />"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:<br /><br />"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:<br /><br />"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](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`**.<br /><br />Example:<br /><br />"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:<br /><br />"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:<br /><br />"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:<br /><br />"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:<br /><br />"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:<br /><br />"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:<br /><br />"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.<br /><br />Example highlighting select attributes:<br /><br /> \{ "user": \<br/>    "id": 6253282,<br />    "id\_str": "6253282",<br />    "name": "X API",<br />    "screen\_name": "API",<br />    "location": "San Francisco, CA",<br />    "url": "[https://developer.x.com](https://developer.x.com)",<br />    "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.",<br />    "verified": true,<br />    "followers\_count": 6129794,<br />    "friends\_count": 12,<br />    "listed\_count": 12899,<br />    "favourites\_count": 31,<br />    "statuses\_count": 3658,<br />    "created\_at": "Wed May 23 06:01:13 +0000 2007",<br />    "utc\_offset": null,<br />    "time\_zone": null,<br />    "geo\_enabled": false,<br />    "lang": "en",<br />    "contributors\_enabled": false,<br />    "is\_translator": false,<br />    "profile\_background\_color": "null",<br />    "profile\_background\_image\_url": "null",<br />    "profile\_background\_image\_url\_https": "null",<br />    "profile\_background\_tile": null,<br />    "profile\_link\_color": "null",<br />    "profile\_sidebar\_border\_color": "null",<br />    "profile\_sidebar\_fill\_color": "null",<br />    "profile\_text\_color": "null",<br />    "profile\_use\_background\_image": null,<br />    "profile\_image\_url": "null",<br />    "profile\_image\_url\_https": "[https://pbs.twimg.com/profile\\\_images/942858479592554497/BbazLO9L\_normal.jpg](https://pbs.twimg.com/profile\\_images/942858479592554497/BbazLO9L_normal.jpg)",<br />    "profile\_banner\_url": "[https://pbs.twimg.com/profile\_banners/6253282/1497491515](https://pbs.twimg.com/profile_banners/6253282/1497491515)",<br />    "default\_profile": false,<br />    "default\_profile\_image": false,<br />    "following": null,<br />    "follow\_request\_sent": null,<br />    "notifications": null<br />  }<br />} |
| 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:<br /><br />"coordinates":<br />\<br/>    "coordinates":<br />    \[<br />        -75.14310264,<br />        40.05701649<br />    ],<br />    "type":"Point"<br />}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 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:<br /><br />"place":<br />\<br/>  "attributes":,<br />   "bounding\_box":<br />  \<br/>     "coordinates":<br />     \[\[<br />           \[-77.119759,38.791645],<br />           \[-76.909393,38.791645],<br />           \[-76.909393,38.995548],<br />           \[-77.119759,38.995548]<br />     ]],<br />     "type":"Polygon"<br />  },<br />   "country":"United States",<br />   "country\_code":"US",<br />   "full\_name":"Washington, DC",<br />   "id":"01fbe706f872cb32",<br />   "name":"Washington",<br />   "place\_type":"city",<br />   "url":"[http://api.x.com/1/geo/id/0172cb32.json](http://api.x.com/1/geo/id/0172cb32.json)"<br />}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 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:<br /><br />"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:<br /><br />"quoted\_status\_id\_str":"1050119905717055488"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| is\_quote\_status              | Boolean                                                                                            | Indicates whether this is a Quoted Tweet. Example:<br /><br />"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:<br /><br />"quote\_count":33<br /><br />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:<br /><br />"reply\_count":30<br /><br />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:<br /><br />"retweet\_count":160                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| favorite\_count                | Integer                                                                                            | *Nullable.* Indicates approximately how many times this Post has been liked by X users. Example:<br /><br />"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:<br /><br />"entities":<br />\<br/>    "hashtags":\[],<br />    "urls":\[],<br />    "user\_mentions":\[],<br />    "media":\[],<br />    "symbols":\[]<br />    "polls":\[]<br />}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 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:<br /><br />"entities":<br />\<br/>    "media":\[]<br />}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| favorited                      | Boolean                                                                                            | *Nullable.* Indicates whether this Post has been liked by the authenticating user. Example:<br /><br />"favorited":true                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| retweeted                      | Boolean                                                                                            | Indicates whether this Post has been Retweeted by the authenticating user. Example:<br /><br />"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.<br /><br />This may also be judged and labeled by an internal X support agent.<br /><br />"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.<br /><br />Example:<br /><br />"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. <br /><br /> Example:<br /><br />"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. <br /><br />The Post IDs can be used to hydrate and view previous versions of a Post.<br /><br />Example:<br /><br />edit\_history": \<br/>    "initial\_tweet\_id": "1283764123"<br />    "edit\_tweet\_ids": \["1283764123", "1394263866"]<br />  }                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 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. <br /><br />The Post IDs can be used to hydrate and view previous versions of a Post.<br /><br />Example:<br /><br />"edit\_controls": \<br/>     "editable\_until\_ms": 123<br />     "edits\_remaining": 3   <br />  }                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 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:<br /><br />\* Posts is promoted<br />\* Post has a poll<br />\* Post is a non-self-thread reply<br />\* Post is a retweet (note that Quote Tweets are eligible for edit)<br />\* Post is nullcast<br />\* Community Post<br />\* Superfollow Post<br />\* 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. <br /><br />Example:<br /><br />"matching\_rules": " \[\<br/>        "tag": "xapi emojis",<br />        "id": 1050118621198921728,<br />        "id\_str": "1050118621198921728"<br />    }]"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

##### 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:<br /><br />"current\_user\_retweet": \<br/>  "id": 6253282,<br />  "id\_str": "6253282"<br />}                                                                                                                |
| 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:<br /><br />"scopes":\{"followers":false}                                                                                                                                                                                                                   |
| paid\_partnership       | Boolean         | Indicates if this Post is a paid partnership, i.e., it has been disclosed by the author as containing paid promotion. Example:<br /><br />"paid\_partnership": true                                                                                                                                                                                                                                       |
| 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:<br /><br />"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:<br /><br />“XX” - Content is withheld in all countries “XY” - Content is withheld due to a DMCA request.<br /><br />Example:<br /><br />"withheld\_in\_countries": \["GR", "HK", "MY"] |
| withheld\_scope         | String          | When present, indicates whether the content being withheld is the “status” or a “user.”<br /><br />Example:<br /><br />"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 title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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 title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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 title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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 title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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:<br /><br />"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:<br /><br />"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:<br /><br />"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:<br /><br />"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:<br /><br />"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:<br /><br />"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:<br /><br />"url": "[https://developer.x.com](https://developer.x.com)"                                                                                                                                                                                                                                                                                                                                                                                                                    |
| description                | String                       | *Nullable* . The user-defined UTF-8 string describing their account. Example:<br /><br />"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:<br /><br />"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:<br /><br />"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:<br /><br />"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:<br /><br />"friends\_count": 32                                                                                                                                                                                                                                                                                                                                                                                |
| listed\_count              | Int                          | The number of public lists that this user is a member of. Example:<br /><br />"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:<br /><br />"favourites\_count": 13                                                                                                                                                                                                                                                                                                                                                                                                |
| statuses\_count            | Int                          | The number of Posts (including retweets) issued by the user. Example:<br /><br />"statuses\_count": 42                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| created\_at                | String                       | The UTC datetime that the user account was created on X. Example:<br /><br />"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) .<br /><br />Example:<br /><br />"profile\_banner\_url": "[https://si0.twimg.com/profile\_banners/819797/1348102824](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:<br /><br />"profile\_image\_url\_https":<br />"[https://abs.twimg.com/sticky/default\\\_profile\\\_images/default\\\_profile\\\_normal.png](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:<br /><br />"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:<br /><br />"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:<br /><br />"id":"01a9a39529b27f36"                                                                                                                                                                                                                                                                                                                                                                                                                             |
| url           | String                     | URL representing the location of additional place metadata for this place. Example:<br /><br />"url":"[https://api.x.com/1.1/geo/id/01a9a39529b27f36.json](https://api.x.com/1.1/geo/id/01a9a39529b27f36.json)"                                                                                                                                                                                                                                                                                                                                                |
| place\_type   | String                     | The type of location represented by this place. Example:<br /><br />"place\_type":"city"                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| name          | String                     | Short human-readable representation of the place’s name. Example:<br /><br />"name":"Manhattan"                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| full\_name    | String                     | Full human-readable representation of the place’s name. Example:<br /><br />"full\_name":"Manhattan, NY"                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| country\_code | String                     | Shortened country code representing the country containing this place. Example:<br /><br />"country\_code":"US"                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| country       | String                     | Name of the country containing this place. Example:<br /><br />"country":"United States"                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| bounding\_box | [Object](#obj-boundingbox) | A bounding box of coordinates which encloses this place. Example:<br /><br /><br />  "bounding\_box": <br />    "coordinates": \[<br />      \[<br />        \[<br />          -74.026675,<br />          40.683935<br />        ],<br />        \[<br />          -74.026675,<br />          40.877483<br />        ],<br />        \[<br />          -73.910408,<br />          40.877483<br />        ],<br />        \[<br />          -73.910408,<br />          40.3935<br />        ]<br />      ]<br />    ],<br />    "type": "Polygon"<br />  <br /> |
| attributes    | Object                     | When using PowerTrack, 30-Day and Full-Archive Search APIs, and Volume Streams this hash is null. Example:<br /><br />"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:<br /><br /><br />  "coordinates": \[<br />    \[<br />      \[<br />        -74.026675,<br />        40.683935<br />      ],<br />      \[<br />        -74.026675,<br />        40.877483<br />      ],<br />      \[<br />        -73.910408,<br />        40.877483<br />      ],<br />      \[<br />        -73.910408,<br />        40.3935<br />      ]<br />    ]<br />  ]<br /> |
| 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:<br /><br />"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:<br /><br />\*\*  "geo": **<br /><br />**"type":\*\* "Point"**,**<br /><br />\*\*    "coordinates": \[**<br /><br /> 54.27784**,**<br /><br /> -0.41068<br /><br />**    ]**<br /><br />**  \*\* |
| type        | String              | The type of data encoded in the coordinates property. This will be “Point” for Post coordinates fields. Example:<br /><br />"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:<br /><br />\*\*  "coordinates": **<br /><br />**"type":\*\* "Point"**,**<br /><br />\*\*    "coordinates": \[**<br /><br /> -0.41068**,**<br /><br /> 54.27784<br /><br />**    ]**<br /><br />**  \*\* |
| type        | String              | The type of data encoded in the coordinates property. This will be “Point” for Post coordinates fields. Example:<br /><br />"type": "Point"                                                                                                                                                                                 |

#### Derived locations

|         |                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| :------ | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Field   | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| derived | locations object | Derived location from the profile geo enrichment  <br />  <br /> **"derived": **<br /><br />**      "locations": \[**<br /><br />\*\*        **<br /><br />**"country":\*\* "United Kingdom"**,**<br /><br />**"country\_code":** "GB"**,**<br /><br />**"locality":** "Yorkshire"**,**<br /><br />**"region":** "England"**,**<br /><br />**"full\_name":** "Yorkshire, England, United Kingdom"**,**<br /><br />\*\*          "geo": **<br /><br />**            "coordinates": \[**<br /><br /> -1.5**,**<br /><br /> 54<br /><br />**            ],**<br /><br />**"type":\*\* "point"<br /><br />\*\*          **<br /><br />**        **<br /><br />**      ]**<br /><br />**    \*\* |

#### Examples:

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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": {

    }
  }
}
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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:<br /><br /><br />  "hashtags": \[<br />    <br />      "indices": \[<br />        32,<br />        38<br />      ],<br />      "text": "nodejs"<br />    <br />  ]<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| media          | Array of [Media Objects](#media)           | Represents media elements uploaded with the Post. Example:<br /><br /><br />  "media": \[<br />    <br />      "display\_url": "pic.x.com/5J1WJSRCy9",<br />      "expanded\_url": "[https://x.com/nolan\\\_test/status/930077847535812610/photo/1](https://x.com/nolan\\_test/status/930077847535812610/photo/1)",<br />      "id": 9.300778475358126e17,<br />      "id\_str": "930077847535812610",<br />      "indices": \[<br />          13,<br />          36<br />      ],<br />      "media\_url": "[http://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg](http://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg)",<br />      "media\_url\_https": "[https://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg](https://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg)"<br />      "sizes": <br />          "thumb": <br />               "h": 150,<br />               "resize": "crop",<br />               "w": 150<br />          ,<br />          "large": <br />              "h": 1366,<br />              "resize": "fit",<br />              "w": 2048<br />          ,<br />          "medium": <br />              "h": 800,<br />              "resize": "fit",<br />              "w": 1200<br />          ,<br />          "small": <br />              "h": 454,<br />              "resize": "fit",<br />              "w": 680<br />          <br />      ,<br />      "type": "photo",      <br />      "url": "[https://t.co/5J1WJSRCy9](https://t.co/5J1WJSRCy9)",<br />    <br />  ]<br /> |
| urls           | Array of [URL Objects](#urls)              | Represents URLs included in the text of a Post.<br /><br />Example (without Enhanced URLs enrichment enabled):<br /><br /><br />  "urls": \[<br />    <br />      "indices": \[<br />        32,<br />        52<br />      ],<br />      "url": "[http://t.co/IOwBrTZR](http://t.co/IOwBrTZR)",<br />      "display\_url": "youtube.com/watch?v=oHg5SJ…",<br />      "expanded\_url": "[http://www.youtube.com/watch?v=oHg5SJYRHA0](http://www.youtube.com/watch?v=oHg5SJYRHA0)"<br />    <br />  ]<br /><br /><br />Example (with Enhanced URLs enrichment enabled):<br /><br />"urls": \[<br />      <br />        "url": "[https://t.co/D0n7a53c2l](https://t.co/D0n7a53c2l)",<br />        "expanded\_url": "[http://bit.ly/18gECvy](http://bit.ly/18gECvy)",<br />        "display\_url": "bit.ly/18gECvy",<br />        "unwound": <br />          "url": "[https://www.youtube.com/watch?v=oHg5SJYRHA0](https://www.youtube.com/watch?v=oHg5SJYRHA0)",<br />          "status": 200,<br />          "title": "RickRoll'D",<br />          "description": "[http://www.facebook.com/rickroll548](http://www.facebook.com/rickroll548) As long as trolls are still trolling, the Rick will never stop rolling."<br />        ,<br />        "indices": \[<br />          62,<br />          85<br />        ]<br />      <br />    ]<br />                                                                                                                                             |
| user\_mentions | Array of [User Mention Objects](#mentions) | Represents other X users mentioned in the text of the Post. Example:<br /><br /><br />  "user\_mentions": \[<br />    <br />      "name": "X API",<br />      "indices": \[<br />        4,<br />        15<br />      ],<br />      "screen\_name": "xapi",<br />      "id": 6253282,<br />      "id\_str": "6253282"<br />    <br />  ]<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| symbols        | Array of [Symbol Objects](#symbols)        | Represents symbols, i.e. \$cashtags, included in the text of the Post. Example:<br /><br /><br />  "symbols": \[<br />    <br />      "indices": \[<br />        12,<br />        17<br />      ],<br />      "text": "twtr"<br />    <br />  ]<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| polls          | Array of [Poll Objects](#polls)            | Represents X Polls included in the Post. Example:<br /><br />"polls": \[<br />      <br />        "options": \[<br />          <br />            "position": 1,<br />            "text": "I read documentation once."<br />          ,<br />          <br />            "position": 2,<br />            "text": "I read documentation twice."<br />          },<br />          <br />            "position": 3,<br />            "text": "I read documentation over and over again."<br />          }<br />        ],<br />        "end\_datetime": "Thu May 25 22:20:27 +0000 2017",<br />        "duration\_minutes": 60<br />      <br />    ]<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

### 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:<br /><br />"indices":\[32,38] |
| text    | String       | Name of the hashtag, minus the leading ‘#’ character. Example:<br /><br />"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:<br /><br />"display\_url":"pic.x.com/rJC5Pxsu"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| expanded\_url           | String               | An expanded version of display\_url. Links to the media display page. Example:<br /><br />"expanded\_url": "[http://x.com/yunorno/status/114080493036773378/photo/1](http://x.com/yunorno/status/114080493036773378/photo/1)"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| id                      | Int64                | ID of the media expressed as a 64-bit integer. Example:<br /><br />"id":114080493040967680                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| id\_str                 | String               | ID of the media expressed as a string. Example:<br /><br />"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:<br /><br />"indices":\[15,35]                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| media\_url              | String               | An http\:// URL pointing directly to the uploaded media file. Example:<br /><br />"media\_url":"[http://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg](http://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg)"<br /><br />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.<br /><br />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. <br /><br />You cannot directly embed these images in a web page.<br /><br />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:<br /><br />"media\_url\_https":"[https://p.twimg.com/AZVLmp-CIAAbkyy.jpg](https://p.twimg.com/AZVLmp-CIAAbkyy.jpg)"<br /><br />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.<br /><br />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. <br /><br />You cannot directly embed these images in a web page.<br /><br />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:<br /><br /><br />  "sizes": <br />    "thumb": <br />      "h": 150,<br />      "resize": "crop",<br />      "w": 150<br />    },<br />    "large": <br />      "h": 1366,<br />      "resize": "fit",<br />      "w": 2048<br />    },<br />    "medium": <br />      "h": 800,<br />      "resize": "fit",<br />      "w": 1200<br />    },<br />    "small": <br />      "h": 454,<br />      "resize": "fit",<br />      "w": 680<br />    }<br />  }<br />}<br /><br />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:<br /><br />"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:<br /><br />"source\_status\_id\_str": "205282515685081088"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| type                    | String               | Type of uploaded media. Possible types include photo, video, and animated\_gif. Example:<br /><br />"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:<br /><br />"url":"[http://t.co/rJC5Pxsu](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:<br /><br />"thumb":"h":150, "resize":"crop", "w":150}<br /><br />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:<br /><br />"large":"h":454, "resize":"fit", "w":680}<br /><br />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:<br /><br />"medium":"h":800, "resize":"fit", "w":1200}<br /><br />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:<br /><br />"small":"h":1366, "resize":"fit", "w":2048}<br /><br />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:<br /><br />"w":150                                                                                                                                                                                                                        |
| h      | Int    | Height in pixels of this size. Example:<br /><br />"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:<br /><br />"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.<br /><br />For example:  <br /><br />"media\_url\_https": "[https://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg](https://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg)",<br /><br />The base URL is then:  <br /><br />*[https://pbs.twimg.com/media/DOhM30VVwAEpIHq](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.<br /><br />For example:  <br /><br />"media\_url\_https": "[https://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg](https://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg)",<br /><br />The format is then: *jpg*                                                                                                                                                                                                                                                                         |
| Name     | The name is the field name of the size to load.<br /><br />For example:<br /><br />  <br /> "sizes":   <br />   "thumb":   <br />     "h": 150,  <br />     "resize": "crop",  <br />     "w": 150  <br />   ,  <br />   "large": <br />     "h": 1366,  <br />     "resize": "fit",  <br />     "w": 2048  <br />   },  <br />   "medium": <br />     "h": 800,  <br />     "resize": "fit",  <br />     "w": 1200  <br />   },  <br />   "small": <br />     "h": 454,  <br />     "resize": "fit",  <br />     "w": 680  <br />   }  <br /> }  <br />}<br /><br />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.<br /><br />*\<base\_url>.\<format>:\<name>*  <br /><br />For example:  <br /><br />*[https://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg:large](https://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg:large)  <br />*                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 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.<br /><br />*\<base\_url>?format=\<format>\&name=\<name>*  <br /><br />For example:  <br /><br />*[https://pbs.twimg.com/media/DOhM30VVwAEpIHq?format=jpg\&name=large](https://pbs.twimg.com/media/DOhM30VVwAEpIHq?format=jpg\&name=large)  <br />*<br /><br />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:<br /><br />"display\_url":"bit.ly/2so49n2"                                                                                                                                                                                                                                                        |
| expanded\_url | String       | Expanded version of ` display_url` . Example:<br /><br />"expanded\_url":"[http://bit.ly/2so49n2](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:<br /><br />"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:<br /><br />"url":"[https://t.co/yzocNFvJuL](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:<br /><br />"url":"[https://blog.x.com/en\_us/topics/insights/2016/using-twitter-as-a-go-to-communication-channel-during-severe-weather-events.html](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:<br /><br />200                                                                                                                                                                                                                                                           |
| title       | String | HTML title for the link. Example:<br /><br />"title":"Using X as a ‘go-to’ communication channel during severe weather"                                                                                                                                                                                                                                   |
| description | String | HTML description for the link. Example:<br /><br />"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:<br /><br />"id":6253282                                                                                                                                                                                                                                                                           |
| id\_str      | String       | If of the mentioned user, as a string. Example:<br /><br />"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:<br /><br />"indices":\[4,15] |
| name         | String       | Display name of the referenced user. Example:<br /><br />"name":"API"                                                                                                                                                                                                                                                                               |
| screen\_name | String       | Screen name of the referenced user. Example:<br /><br />"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:<br /><br />"indices":\[12,17] |
| text    | String       | Name of the cashhtag, minus the leading ‘\$’ character. Example:<br /><br />"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:<br /><br />"options": \[<br />          <br />            "position": 1,<br />            "text": "I read documentation once."<br />          }<br />      ]<br />} |
| end\_datetime     | String                 | Time stamp (UTC) of when poll ends. Example:<br /><br />"end\_datetime": "Thu May 25 22:20:27 +0000 2017"                                                                                                                                                      |
| duration\_minutes | String                 | Duration of poll in minutes. Example:<br /><br />"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](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 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](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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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.

```json theme={null}
{
      "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:

<iframe />

Here is the `entities` section for this Post:

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
      "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:

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
    "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:

<iframe />

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
      "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 title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
      "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 title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
    "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

<iframe title="X Post" />

Below is the extended entities metadata for this Post with an animated GIF:

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
      "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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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": "<a href=\"https://mobile.x.com\" rel=\"nofollow\">X Web App</a>",
	"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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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": "<a href=\"https://mobile.x.com\" rel=\"nofollow\">X Web App</a>",
	"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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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": "<a href=\"https://mobile.x.com\" rel=\"nofollow\">X Web App</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": 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\_entities

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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": "<a href=\"https://mobile.x.com\" rel=\"nofollow\">X Web App</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": 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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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": "<a href=\"https://mobile.x.com\" rel=\"nofollow\">X Web App</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": "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": "<a href=\"https://mobile.x.com\" rel=\"nofollow\">X Web App</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": 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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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": "<a href=\"https://mobile.x.com\" rel=\"nofollow\">X Web App</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": 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": "<a href=\"https://mobile.x.com\" rel=\"nofollow\">X Web App</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": 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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
 {
 	"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": "<a href=\"http://x.com/download/iphone\" rel=\"nofollow\">X for iPhone</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": "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": "<a href=\"https://mobile.x.com\" rel=\"nofollow\">X Web App</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": 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": "<a href=\"https://mobile.x.com\" rel=\"nofollow\">X Web App</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": 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": "<a href=\"https://mobile.x.com\" rel=\"nofollow\">X Web App</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": 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

<Note>
  Interested in learning more about how the Activity Streams data format maps to the X API v2 format?
</Note>

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)

<Note>
  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.
</Note>

### 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.  <br />When storing Posts, this should be used as the unique identifier or primary key.  <br />"id": "tag:search.x.com,2005:1050118621198921728"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| objectType                  | string          | Type of object, always set to "activity"  <br />"objectType": "activity"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| object                      | object          | An object representing post being posted or shared.  <br />For Retweets, this will contain an entire "activity", with the pertinent fields described in this schema.  <br />For Original posts, this will contain a "note" object, with the fields described here.  <br />"object":  <br />"object": <br />"objectType": "note",  <br />"id": "object:search.x.com,2005:1050118621198921728",  <br />"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](https://t.co/MkGjXf9aXm)",  <br />"link": "[http://x.com/API/statuses/1050118621198921728](http://x.com/API/statuses/1050118621198921728)",  <br />"postedTime": "2018-10-10T20:19:24.000Z"  <br />                                                                                                                                                                                                                                                                                                                                                              |
| long\_object                | object          | An object representing the full text body if the post text extends beyond 140 characters.  <br />  <br />  <br />"long\_object": <br />"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](https://t.co/Nx1XZmRCXA)",  <br />"display\_text\_range": \[  <br />0,  <br />277  <br />],  <br />"twitter\_entities": <br />"hashtags": \[],  <br />"urls": \[  <br /><br />"url": "[https://t.co/Nx1XZmRCXA](https://t.co/Nx1XZmRCXA)",  <br />"expanded\_url": "[https://devcommunity.x.com/t/new-update-to-the-twitter-text-library-emoji-character-count/114607](https://devcommunity.x.com/t/new-update-to-the-twitter-text-library-emoji-character-count/114607)",  <br />"display\_url": "devcommunity.com/t/new-update-t…",  <br />"indices": \[  <br />254,  <br />277  <br />]  <br />  <br />],  <br />"user\_mentions": \[],  <br />"symbols": \[]  <br />  <br /> |
| display\_text\_range        | array           | if the post text extends beyond 140 characters.  <br />  <br />  <br />"display\_text\_range": \[  <br />0,  <br />142  <br />]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| verb                        | string          | [The type of action being taken by the user.  <br />Posts, "post"  <br />Retweets, "share"  <br />Deleted Posts, "delete"  <br />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).  <br />For Deletes, note that only a limited number of fields will be included, as shown in the sample payload below.  <br />"verb": "post"                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| postedTime                  | date (ISO 8601) | The time the action occurred, e.g. the time the post was posted.  <br />  <br />  <br />"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.  <br />"generator": <br />"displayName": "X Web Client",  <br />"link": "[http://x.com](http://x.com)"  <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 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").  <br />"provider":  <br /><br />"objectType": "service",  <br />"displayName": "X",  <br />"link": "[http://www.x.com](http://www.x.com)"  <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| link                        | string          | A Permalink for the post.  <br />"link": "[http://x.com/API/statuses/1050118621198921728](http://x.com/API/statuses/1050118621198921728)"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| body                        | string          | The post text.  <br />  <br />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).  <br />"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.  <br />  <br />"display\_text\_range": \[  <br />14,  <br />42  <br />]  <br />or  <br />"long\_object": <br />"display\_text\_range": \[  <br />0,  <br />277  <br />]...                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 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.  <br />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.  <br />"inReplyTo":  <br /><br />"link": "http:\\/\\/x.com\\/GOP\\/statuses\\/349573991561838593"  <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| location                    | object          | [A JSON object representing the X "Place" where the post was created. This is an object passed through from the X platform.  <br />  <br />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.  <br />  <br />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.  <br />  <br />Multiple photos are represented by comma-separated JSON objects within the "media" array.  <br />  <br />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.  <br />  <br />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. <br /><br />The Post IDs can be used to hydrate and view previous versions of a Post.<br /><br />Example:<br /><br />edit\_history": <br />    "initial\_tweet\_id": "1283764123"<br />    "edit\_tweet\_ids": \["1283764123", "1394263866"]<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 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. <br /><br />The Post IDs can be used to hydrate and view previous versions of a Post.<br /><br />Example:<br /><br />"edit\_controls": <br />     "editable\_until\_ms": 123<br />     "edits\_remaining": 3   <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 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:<br /><br />\* Posts is promoted<br />\* Post has a poll<br />\* Post is a non-self-thread reply<br />\* Post is a retweet (note that Quote Tweets are eligible for edit)<br />\* Post is nullcast<br />\* Community Post<br />\* Superfollow Post<br />\* 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.  <br />  <br />"favoritesCount":298 |
| retweetCount   | int    | Number of times this Post has been retweeted. Example:<br /><br />"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.

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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 embedded 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:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
    	"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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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:<br /><br />"id:x.com:2244994945"                                                                                                                                                                                                                                        |
| link              |         | "[http://www.x.com/XDevelopers](http://www.x.com/XDevelopers)"                                                                                                                                                                                                                                                                                       |
| 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:<br /><br />**"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:<br /><br />**"preferredUsername":** "XDevelopers"                          |
| location          | object  | \*\*        "location": **<br /><br />**"objectType":\*\* "place"**,**<br /><br />**"displayName":** "127.0.0.1"<br /><br />\*\*        }\*\*                                                                                                                                                                                                        |
| links             | array   | *Nullable* . A URL provided by the user in association with their profile. Example:<br /><br />\*\*       "links": \[**<br /><br />**          \{ **<br /><br />**"href":\*\* "[https://developer.x.com/en/community](https://developer.x.com/en/community)"**,**<br /><br />**"rel":** "me"<br /><br />\*\*          }**<br /><br />**        ]\*\* |
| summary           | string  | *Nullable* . The user-defined UTF-8 string describing their account. Example:<br /><br />**"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:<br /><br />"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:<br /><br />"verified": false                                                                                                                                                       |
| followersCount    | Int     | The number of followers this account currently has. Under certain conditions of duress, this field will temporarily indicate “0”. Example:<br /><br />"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:<br /><br />"friends\_count": 32                                                                                                                                                       |
| listedCount       | Int     | The number of public lists that this user is a member of. Example:<br /><br />"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:<br /><br />"favourites\_count": 13                                                                                                                                                                       |
| statusesCount     | Int     | The number of Posts (including retweets) issued by the user. Example:<br /><br />"statuses\_count": 42                                                                                                                                                                                                                                               |
| postedTime        | date    | The UTC datetime that the user account was created on X. Example:<br /><br />**"postedTime":** "2013-12-14T04:35:55.036Z"                                                                                                                                                                                                                            |
| image             | string  | A HTTPS-based URL pointing to the user’s profile image. Example:<br /><br />**"image":** "[https://pbs.twimg.com/profile\\\_images/1283786620521652229/lEODkLTh\\\_normal.jpg](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 objects can exist within the actor object 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:<br /><br />**"objectType":** "place"                                             |
| displayName | string | **The full name of the location.  <br />  <br />\*\*\*\*"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.  <br />  <br />**"link":** "[https://api.x.com/1.1/geo/id/27c45d804c777999.json](https://api.x.com/1.1/geo/id/27c45d804c777999.json)" |
| geo         | object | The geo coordintates object from X.  Either a polygon, or point.<br /><br />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:<br /><br /> **"countryCode": "US**                                                                           |
| country     | String | Name of the country containing this place. Example:<br /><br />\*\*"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 enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo).  Level of granularity will vary. <br /><br />**"address": \{**<br /><br />\*\*          "country": **"United States"**,**<br /><br />**          "countryCode": **"US"**,**<br /><br />**          "locality": **"Providence"**,**<br /><br />**          "region": **"Rhode Island"**,**<br /><br />**          "subRegion": **"Providence County"<br /><br />**        }\*\* |
| geo     | object | Within profileLocation location object within the [gnip object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#gnip-object). Centroid coordinates of the location derived by the [profile geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo).<br /><br />**"geo": \{**<br /><br />\*\*          "coordinates": \[**<br /><br />-98.5**,**<br /><br />39.76<br /><br />**          ],**<br /><br />**          "type": **"point"<br /><br />**        }\*\*                                                                                                                                                   |

**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.  <br /> **"matching\_rules": \[**<br /><br />\*\*      \{**<br /><br />**        "tag": null,**<br /><br />**"id":\*\* 1026514022567358500\*\*,**<br /><br />**"id\_str":\*\* "1026514022567358464"<br /><br />\*\*      }**<br /><br />**    ]\*\*                                                                                                                                                                                                                                                                                                                                                                                                                        |
| urls             | array                     | Contains an array of the links within the activity, and the expanded url metadata for the **URL unwinding enrichment**  <br />  <br />\*\*    "urls": \[**<br /><br />**      \{**<br /><br />**"url":\*\* "[https://t.co/tGQqNxxyhU](https://t.co/tGQqNxxyhU)"**,**<br /><br />**"expanded\_url":** "[https://www.youtube.com/channel/UCwUxW2CV2p5mzjMBqvqLzJA](https://www.youtube.com/channel/UCwUxW2CV2p5mzjMBqvqLzJA)"**,**<br /><br />**"expanded\_status":** 200\*\*,**<br /><br />**"expanded\_url\_title":\*\* "Birdys Daughter"**,**<br /><br />**"expanded\_url\_description":** "Premium, single-origin, handpicked Jamaica Blue Mountain Coffee"<br /><br />\*\*      }**<br /><br />**    ]\*\*                                                                |
| profileLocations | array of location objects | Contains the derived location object from the Profile Geo enrichment  <br />  <br />\*\*    "profileLocations": \[**<br /><br />**      \{**<br /><br />**        "address": \{**<br /><br />**"country":\*\* "Canada"**,**<br /><br />**"countryCode":** "CA"**,**<br /><br />**"locality":** "Toronto"**,**<br /><br />**"region":** "Ontario"<br /><br />\*\*        },**<br /><br />**"displayName":\*\* "Toronto, Ontario, Canada"**,**<br /><br />\*\*        "geo": \{**<br /><br />**          "coordinates": \[**<br /><br /> -79.4163**,**<br /><br /> 43.70011<br /><br />**          ],**<br /><br />**"type":\*\* "point"<br /><br />\*\*        },**<br /><br />**"objectType":\*\* "place"<br /><br />\*\*      }**<br /><br />**    ]**<br /><br />**  }\*\* |

#### Example:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
	"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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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`

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
 {
 	"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

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
	"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 an 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](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.


# Data enrichments: Enterprise
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments

Enterprise Gnip data enrichments add metadata to payloads, including expanded URLs, matching rules, poll details, and profile geo coordinates.

## 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 `entities.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 title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
"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>
  **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).
</Note>

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"
```


# Decahose API
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/decahose-api

Stream a random 10% sample of all realtime public Posts and likes through the enterprise Decahose API with partitioning and URL enrichment.

<Note>
  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). 
</Note>

### 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/\&lt;accountName\&gt;/publishers/twitter/\&lt;streamLabel\&gt;.json?partition=1](https://gnip-stream.x.com/stream/sample10-likes/accounts/\&lt;accountName\&gt;/publishers/twitter/\&lt;streamLabel\&gt;.json?partition=1)

**Native enriched format payload**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
   "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 theme={null}
{
   "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](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 disconnecte


# Edit Tweets
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets

Understand enterprise Post edit metadata, including edit_history, edit_controls, and editable fields returned in Gnip and enterprise API payloads.

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. 

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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. 

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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. 

```json theme={null}
{
  "tweet_edit": {
    "id": <tweetId>,
    "initial_tweet_id": <tweetId>,
    "edit_tweet_ids": [<tweetId1>, <tweetId2>, <tweetId3> ...],
    "timestamp_ms": "<timestampMsStr>"
  }
}
```


# Engagement API
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/engagement-api

Retrieve impression and engagement metrics for Posts with the enterprise Engagement API using totals, 28-hour, and historical request endpoints.

## 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<br /><br />No - /totals | A count of how many times the Post has been favorited.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| retweets                                                                                                                                             | All                   | Yes - /28hrs & /Historical<br /><br />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<br /><br />No - /totals | A count of how many times the Post has been replied to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| video\_views                                                                                                                                         | All                   | Yes - /28hrs & /Historical<br /><br />No - /totals | A count of how many times a video in the given Post has been 50% visible for at least two seconds.<br /><br />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:<br /><br />"unsupported\_for\_video\_views\_tweet\_ids": \["TWEET\_ID"]<br /><br />**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.  <br /><br />\*   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.<br />\*   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<br /><br />([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 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).


# Compliance Firehose API
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/firehouse

Stream realtime user compliance events such as deletes, edits, withholdings, and scrubs with the enterprise Compliance Firehose API for stored data.

> **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 addition, 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 theme={null}
{"tweet_edit":
   {
     "id": "1557445923210514432"
     "initial_tweet_id": "1557433858676740098",
     "edit_tweet_ids": ["1557433858676740098", "1557445923210514432"],
     "timestamp_ms": "1660155761384"
   }
 }
```

##### Post delete

```json theme={null}
{
  "delete": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220608",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}
```

##### Post withheld

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "status_withheld": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220608",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "withheld_in_countries": [
      "XY"
    ],
    "timestamp_ms": "1432228155593"
  }
}
```

##### Drop

```json theme={null}
{
  "drop": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220600",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}
```

##### Undrop

```json theme={null}
{
  "undrop": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220600",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}
```

#### Scrub geo

```json theme={null}
{
  "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 theme={null}
{
  "user_delete": {
    "id": 771136850,
    "timestamp_ms": "1432228153548"
  }
}
```

##### User undelete

```json theme={null}
{
  "user_undelete": {
    "id": 796250066,
    "timestamp_ms": "1432228149062"
  }
}
```

##### User withheld

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "user_withheld": {
    "user": {
      "id": 1375036644,
      "id_str": "1375036644"
    },
    "withheld_in_countries": [
      "XY"
    ],
    "timestampMs": "2014-08-27T23:49:41.839+00:00"
  }
}
```

##### User protect

```json theme={null}
{
  "user_protect": {
    "id": 3182003550,
    "timestamp_ms": "1432228177137"
  }
}
```

##### User unprotect

```json theme={null}
{
  "user_unprotect": {
    "id": 2911076065,
    "timestamp_ms": "1432228180113"
  }
}
```

##### User suspend

```json theme={null}
{
  "user_suspend": {
    "id": 3120539094,
    "timestamp_ms": "1432228194217"
  }
}
```

##### User unsuspend

```json theme={null}
{
  "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).


# Gnip console
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/overview

Overview of the enterprise Gnip console at console.gnip.com for managing enterprise X API access, product details, usage metrics, and account settings.

## 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.**

<video>
  <source type="video/mp4" />

  Your browser does not support the video tag.
</video>

## 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 programmatically.

Specific details per stream are available by clicking the name, or the settings button.

<Frame>
  <img />
</Frame>

### 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.

<Frame>
  <img />
</Frame>

### 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).

<Frame>
  <img />
</Frame>

### 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.

<Frame>
  <img />
</Frame>

### 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.

<Frame>
  <img />
</Frame>

### 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).

<Frame>
  <img />
</Frame>

## 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](https://api.twitterstat.us).

### Account Settings

You may add, remove, and edit users, and configure email notifications for individual users and usage threshold alerts.

<Frame>
  <img />
</Frame>

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.

<Frame>
  <img />
</Frame>

Please note that these thresholds are evaluated once per day at 19:30 (UTC), and are not evaluated in real-time.


# Rate limits: Enterprise
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/rate-limits

Review request rate limits for enterprise Gnip APIs including PowerTrack, Decahose, Search, Account Activity, Engagement, and Compliance Firehose.

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


# Rules and filtering: Enterprise
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering

Build enterprise PowerTrack and Search rules using keyword, phrase, proximity, and boolean operators with grouping for precise X data filtering.

## 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:XDevelopers`

**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  <br />  <br />Matches activities containing both keywords ("social", "data").  <br />  <br />**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  <br />  <br />Matches activities with EITHER keyword ("social" OR "data")  <br />  <br />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.  <br />  <br />You must use upper-case "OR" in your rule. Lower-case 'or' will be treated as a regular keyword.                                                                                                       |
| NOT            | social data  <br />-apple -android -phone | Insert a `-` character immediately in front of the operator or group of operators.  <br />  <br />The example rule shown matches activities containing keyword "social", but excludes those which contain the keyword "data."  <br />  <br />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) -XDevelopers -api        | Parentheses around multiple operators create a functional "group".<br /><br />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). <br /><br />For example, instead of using -(iphone OR imac OR macbook), use the following: -iphone -imac -macbook  <br />  <br />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 hashtags, 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 |
| :------- | :---------- |


# Search API: Enterprise
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/search-api

>Please note: > >We have released a new version of search Posts and Post counts in X API v2. We encourage you to review what's new with X API v2.

> **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<br />\* “quoted phrase”<br />\* “keyword1 keyword2”\~N<br />\* #<br />\* @<br />\* \$<br />\* url:<br />\* lang: | \* from:<br />\* to:<br />\* retweets\_of: | \* is:retweet  <br />    <br />\* has:mentions<br />\* has:hashtags<br />\* has:media<br />\* has:videos<br />\* has:images<br />\* has:links<br />\* has:symbols<br />\* is:verified  <br />    <br />\* -is:nullcast (negation only operator) | \* bounding\_box:\[west\_long south\_lat east\_long north\_lat]<br />\* point\_radius:\[lon lat radius]<br />\* has:geo<br />\* place:<br />\* place\_country:<br />\* has:profile\_geo<br />\* profile\_country:<br />\* profile\_region:<br />\* 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 u


# Usage API
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/usage

The Usage API is a free REST API that provides programmatic access and visibility into activity consumption across products for your enterprise account.

## 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 theme={null}
curl -u<username>:<password> \
"https://gnip-api.x.com/metrics/usage/accounts/<account-name>.json?bucket=month"
```

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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 title="Example request" expandable lines wrap icon="terminal" theme={null}
{
  "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/.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](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.  <br />  <br />Requests made without a specified bucket will return monthly granularity.  <br />  <br />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'.  <br />  <br />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.  <br />  <br />**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.  <br />**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'.  <br />  <br />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.  <br />  <br />**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](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.                     |


# PowerTrack API
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/powertrack-api

This endpoint has been updated to include Post edit metadata. Learn more about this metadata on the "Edit Posts" fundamentals page.

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:

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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": "<a href=\"http://x.com\" rel=\"nofollow\">X 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": 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)


# API Consistency
Source: https://docs.x.com/x-api/fundamentals/consistency

Learn the consistent URL, response, and ID patterns used across all X API v2 endpoints so the same conventions apply everywhere you integrate.

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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
// 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

<CardGroup>
  <Card title="Learn once, use everywhere" icon="graduation-cap">
    Patterns you learn on one endpoint apply to all endpoints.
  </Card>

  <Card title="Predictable responses" icon="square-check">
    Same object types have same structures across the API.
  </Card>

  <Card title="Simpler code" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219">
    Build reusable functions for common patterns.
  </Card>

  <Card title="Easier debugging" icon="bug">
    Consistent error formats simplify troubleshooting.
  </Card>
</CardGroup>

***

## Report inconsistencies

Found an inconsistency? Let us know:

* [Developer Forum](https://devcommunity.x.com)
* [Developer Feedback](https://t.co/devfeedback)


# Consuming streaming data
Source: https://docs.x.com/x-api/fundamentals/consuming-streaming-data

Learn how to build robust clients that consume data from X streaming endpoints. X streaming endpoints are categorized by volume: X API streaming endpoints.

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.

<Note>
  If your use case requires lower latency, consider [Powerstream](/x-api/powerstream/introduction), which is optimized for speed and delivers data with minimal delay.
</Note>

<Warning>
  Latency and data delivery may be negatively impacted during outages. Refer to the [status page](https://developer.x.com/status) for updates when issues occur.
</Warning>

***

## 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 theme={null}
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 theme={null}
{
  "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"
  }]
}
```

<Note>
  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.
</Note>

***

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

<Note>
  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`.
</Note>

***

## 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} theme={null}
flowchart LR
    A["Stream Connection<br/>(lightweight)"] --> B["Memory Buffer<br/>(FIFO)"] --> C["Processing Thread(s)<br/>(heavy work)"]
```

***

## Next steps

<CardGroup>
  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Reconnect gracefully when connections drop
  </Card>

  <Card title="High volume capacity" icon="gauge-high" href="/x-api/fundamentals/high-volume-capacity">
    Handle high throughput streams
  </Card>

  <Card title="Recovery and redundancy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055" href="/x-api/fundamentals/recovery-and-redundancy">
    Build resilient streaming applications
  </Card>
</CardGroup>


# Conversation ID
Source: https://docs.x.com/x-api/fundamentals/conversation-id

Every reply on X belongs to a conversation thread. The conversationid field lets you identify, track, and reconstruct entire conversation trees.

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} theme={null}
flowchart TD
    A["Original post (ID: 1234567890)<br/>← conversation_id for all replies"] --> B["Reply 1 (ID: 1234567891)<br/>conversation_id: 1234567890"]
    A --> C["Reply 2 (ID: 1234567892)<br/>conversation_id: 1234567890"]
    B --> D["Reply to Reply 1<br/>conversation_id: 1234567890"]
    C --> E["Reply to Reply 2<br/>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 theme={null}
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 title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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 theme={null}
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

<Tabs>
  <Tab title="Thread reconstruction">
    Build the full conversation tree:

    ```python title="Example" lines wrap icon="python" theme={null}
    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"])
    ```
  </Tab>

  <Tab title="Conversation monitoring">
    Stream replies to specific conversations in real-time:

    ```bash theme={null}
    # 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"}]}'
    ```
  </Tab>

  <Tab title="Conversation analytics">
    Count replies in a conversation:

    ```bash theme={null}
    curl "https://api.x.com/2/tweets/counts/recent?\
    query=conversation_id:1234567890" \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Tab>
</Tabs>

***

## 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 title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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

<CardGroup>
  <Card title="Search posts" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/search/introduction">
    Search by conversation\_id.
  </Card>

  <Card title="Filtered stream" icon="signal-stream" href="/x-api/posts/filtered-stream/introduction">
    Monitor conversations in real-time.
  </Card>
</CardGroup>


# X API v2 data dictionary: Post, User, Space fields
Source: https://docs.x.com/x-api/fundamentals/data-dictionary

Field-level reference for X API v2 JSON objects, including Post (Tweet), User, Space, Media, Poll, and Place, plus expansions and metrics.

The X API returns rich structured JSON. This dictionary documents every available field for each object type.

## Quick navigation

* [Post (Tweet) fields](#post-tweet)
* [User fields](#user)
* [Space, List, Media, Poll, Place, Community, DM events](#space)
* [How to request fields & expansions](#how-to-use-fields-and-expansions)
* [Example payloads](#x-api-v2-example-payloads)

**Full detailed field tables → [Data Dictionary Reference](/x-api/fundamentals/data-dictionary/reference)**

## 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`   |

<Tip>
  Use [fields parameters](/x-api/fundamentals/fields) to request specific fields, and [expansions](/x-api/fundamentals/expansions) to include related objects.
</Tip>

***

## 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.                                        |
| **paid\_partnership**                   | boolean         | Indicates if this Post is a paid partnership, i.e., it has been disclosed by the author as containing paid promotion.                                                                                   | Identify Posts disclosed as paid partnerships / sponsored content.               |
| **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 theme={null}
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,paid_partnership,possibly_sensitive,public_metrics,referenced_tweets,text,withheld&expansions=referenced_tweets.id' --header 'Authorization: Bearer $BEARER_TOKEN'
```

**Sample Response**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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. Includes nested `url` and `description` objects, each containing arrays such as `urls`, `hashtags`, `mentions`, and `cashtags`. See the sample response below for a complete example.                                                      | 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.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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).<br /><br />`"protected": false`                                                                                                                                                                               |                                                                                                                                                                                                                                                                                        |
| public\_metrics            | object          | Contains details about activity for this user.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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).
 

```{ theme={null}
  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**

```{ theme={null}
"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 &amp; respond to the pandemic. \n\nWe're launching a free COVID-19 stream endpoint so qualified devs &amp; 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.<br />`"id": "1zqKVXPQhvZJB"`                  | Uniquely identify a Space returned in the response.     |
| state (default)    | string          | Indicates if the Space has started, will start, or has ended.<br />`"state": "live"`        | Filter live or scheduled Spaces.                        |
| created\_at        | date (ISO 8601) | Creation time of this Space.<br />`"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.<br />`"creator_id": "2244994945"`                   |                                                         |
| ended\_at          | date (ISO 8601) | Time when the Space ended, if applicable.<br />`"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.<br />`"host_ids": ["2244994945", "6253282"]`         | Expand User objects, understand engagement.             |
| lang               | string          | Language of the Space, if detected.<br />`"lang": "en"`                                     | Classify Spaces by language.                            |
| is\_ticketed       | boolean         | Indicates if this is a ticketed Space.<br />`"is_ticketed": false`                          | Highlight content of interest.                          |
| invited\_user\_ids | array           | List of user IDs invited as speakers.<br />`"invited_user_ids": ["2244994945", "6253282"]`  | Expand User objects, understand engagement.             |
| participant\_count | integer         | Number of users in the Space, including Hosts and Speakers.<br />`"participant_count": 420` | Understand engagement, create reports.                  |
| subscriber\_count  | integer         | Number of people who set a reminder for a Space.<br />`"subscriber_count": 36`              | Understand event interest.                              |
| scheduled\_start   | date (ISO 8601) | Scheduled start time of the Space.<br />`"scheduled_start": "2021-07-14T08:00:00.000Z"`     | Integrate with calendar notifications.                  |
| speaker\_ids       | array           | List of users who spoke at any point.<br />`"speaker_ids": ["2244994945", "6253282"]`       | Expand User objects, understand engagement.             |
| started\_at        | date (ISO 8601) | Actual start time of a Space.<br />`"started_at": "2021-07-14T08:00:12.000Z"`               | Determine Space start time.                             |
| title              | string          | Title of the Space.<br />`"title": "Say hello to the Space data object!"`                   | Understand keywords, hashtags, mentions.                |
| topic\_ids         | array           | IDs of topics selected by the Space creator.<br />`"topic_ids": ["2244994945", "6253282"]`  | Understand keywords, hashtags, mentions.                |
| updated\_at        | date (ISO 8601) | Last update to Space metadata.<br />`"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 theme={null}
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.<br />`"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.<br />`"name": "Twitter Lists"`                                                                  |                                                                                |
| created\_at     | date (ISO 8601) | The UTC datetime when the List was created.<br />`"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.<br />`"description": "People that are active members of the Bay area cycling community on Twitter."` |                                                                                |
| follower\_count | integer         | Shows how many users follow this List.<br />`"follower_count": 198`                                                                                      |                                                                                |
| member\_count   | integer         | Shows how many members are part of this List.<br />`"member_count": 60`                                                                                  |                                                                                |
| private         | boolean         | Indicates if the List is private.<br />`"private": false`                                                                                                |                                                                                |
| owner\_id       | string          | Unique identifier of this List's owner.<br />`"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 theme={null}
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. <br /> ` "media_key": "13_1263145212760805376"`                                                                                                                                                                                                                                | Can be used to programmatically retrieve media                                                |
| type (default)       | string  | Type of content (animated\_gif, photo, video). <br /> ` "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. <br /> ` "duration_ms": 46947`                                                                                                                                                                                                                             |                                                                                               |
| height               | integer | Height of this content in pixels. <br /> ` "height": 1080`                                                                                                                                                                                                                                                                      |                                                                                               |
| non\_public\_metrics | object  | Non-public engagement metrics for the media content at the time of the request. Requires user context authentication. <br /> ` "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. <br /> ` "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. <br /> ` "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. <br /> ` "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. <br /> ` "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. <br /> ` "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. <br /> ` "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. <br /> ` "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 theme={null}
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 theme={null}
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 theme={null}
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**

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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.<br /><br />`"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, and ParticipantsLeave.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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.<br /><br />`"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 theme={null}
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. <br /><br /> Can be one of: |    |
|               |                 | - `Public`                                                     |    |
|               |                 | - `Closed`                                                     |    |
| join\_policy  | string          | The join policy for the Community. <br /><br /> 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 theme={null}
curl --location 'https://api.x.com/2/communities/search?query=anime&amp;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"
  }
}
```

***

**Complete field tables and additional examples are in the [Data Dictionary Reference](/x-api/fundamentals/data-dictionary/reference).**


# Data Dictionary Reference
Source: https://docs.x.com/x-api/fundamentals/data-dictionary/reference

Full X API v2 data dictionary reference covering Tweet, User, Media, Place, Poll, and Space object fields and how to request them with expansions.

## 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/reference#tweet) using a Tweet ID and the [GET /tweets endpoint](/x-api/posts/lookup/introduction).

Request:

```bash theme={null}
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/reference#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 theme={null}
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 theme={null}
{
"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 theme={null}
{
"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 theme={null}
{
"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 theme={null}
{
"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"
    }
  ]
}
}
```


# Edit Posts
Source: https://docs.x.com/x-api/fundamentals/edit-posts

Edit Posts on X within a 30-minute window up to five times and read the edit history, edit_controls, and editable metadata returned by the v2 API.

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 theme={null}
{
  "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 theme={null}
curl "https://api.x.com/2/tweets/1234567891?tweet.fields=edit_controls" \
  -H "Authorization: Bearer $TOKEN"
```

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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 theme={null}
curl "https://api.x.com/2/tweets/1234567891?\
tweet.fields=edit_controls&\
expansions=edit_history_tweet_ids" \
  -H "Authorization: Bearer $TOKEN"
```

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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 theme={null}
# 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

<Tabs>
  <Tab title="Track changes">
    Monitor posts for edits and log the differences:

    ```python theme={null}
    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")
    ```
  </Tab>

  <Tab title="Show edit indicator">
    Display an "edited" badge in your UI:

    ```javascript theme={null}
    const isEdited = post.edit_history_tweet_ids?.length > 1;
    if (isEdited) {
      showEditedBadge();
    }
    ```
  </Tab>

  <Tab title="Get original content">
    Retrieve the original version of an edited post:

    ```python theme={null}
    original_id = post["edit_history_tweet_ids"][0]
    original = api.get_tweet(original_id)
    ```
  </Tab>
</Tabs>

***

## Next steps

<CardGroup>
  <Card title="Post lookup" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/lookup/introduction">
    Retrieve posts with edit history.
  </Card>

  <Card title="Data dictionary" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/fundamentals/data-dictionary">
    Complete post object reference.
  </Card>
</CardGroup>


# Expansions
Source: https://docs.x.com/x-api/fundamentals/expansions

Use X API v2 expansions to include related users, media, polls, places, and referenced posts inside the includes section of a single response.

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 theme={null}
curl "https://api.x.com/2/tweets/1234567890?expansions=author_id" \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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 theme={null}
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 title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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 theme={null}
expansions=author_id,referenced_tweets.id,attachments.media_keys
```

***

## Common patterns

<Tabs>
  <Tab title="Full post context">
    Get a post with author, media, and referenced posts:

    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Conversation thread">
    Get replies with their authors:

    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="User with pinned post">
    Get a user profile with their pinned post:

    ```bash theme={null}
    expansions=pinned_tweet_id
    user.fields=description,public_metrics,verified
    tweet.fields=created_at,public_metrics
    ```
  </Tab>
</Tabs>

***

## Linking data and includes

The objects in `includes` don't contain position information. Link them using IDs:

```python theme={null}
# 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 theme={null}
// 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

<CardGroup>
  <Card title="Fields" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/fundamentals/fields">
    Request specific fields for each object.
  </Card>

  <Card title="Data Dictionary" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/fundamentals/data-dictionary">
    Complete object schemas.
  </Card>
</CardGroup>


# Fields
Source: https://docs.x.com/x-api/fundamentals/fields

The X API v2 returns minimal data by default. Use fields parameters to request additional data for each object type. By default, a post lookup returns only.

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 theme={null}
# 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/reference#tweet)  |
| User         | `user.fields`  | [User fields](/x-api/fundamentals/data-dictionary/reference#user)   |
| Media        | `media.fields` | [Media fields](/x-api/fundamentals/data-dictionary/reference#media) |
| Poll         | `poll.fields`  | [Poll fields](/x-api/fundamentals/data-dictionary/reference#poll)   |
| Place        | `place.fields` | [Place fields](/x-api/fundamentals/data-dictionary/reference#place) |

***

## Example: Post fields

Request specific post fields with `tweet.fields`:

```bash theme={null}
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=created_at,public_metrics,lang" \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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 theme={null}
curl "https://api.x.com/2/users/by/username/xdevelopers?user.fields=created_at,description,public_metrics" \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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 theme={null}
# 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 title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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

<Tabs>
  <Tab title="Post analytics">
    ```
    tweet.fields=created_at,public_metrics,possibly_sensitive
    ```
  </Tab>

  <Tab title="User profiles">
    ```
    user.fields=created_at,description,location,public_metrics,verified
    ```
  </Tab>

  <Tab title="Full post context">
    ```
    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
    ```
  </Tab>

  <Tab title="Media details">
    ```
    tweet.fields=attachments
    expansions=attachments.media_keys
    media.fields=url,preview_image_url,alt_text,public_metrics
    ```
  </Tab>
</Tabs>

***

## Important notes

<Warning>
  **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`.
</Warning>

* 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

<CardGroup>
  <Card title="Expansions" icon="expand" href="/x-api/fundamentals/expansions">
    Include related objects in responses.
  </Card>

  <Card title="Data Dictionary" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/fundamentals/data-dictionary">
    Complete field reference for all objects.
  </Card>
</CardGroup>


# Handling disconnections
Source: https://docs.x.com/x-api/fundamentals/handling-disconnections

Learn how to handle disconnections when using X streaming endpoints including Filtered Stream, Volume Streams, Powerstream, and Compliance Streams.

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 theme={null}
{
  "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 theme={null}
{
  "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

<CardGroup>
  <Card title="Recovery and redundancy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055" href="/x-api/fundamentals/recovery-and-redundancy">
    Recover missed data after disconnections
  </Card>

  <Card title="Consuming streaming data" icon="stream" href="/x-api/fundamentals/consuming-streaming-data">
    Build robust streaming clients
  </Card>

  <Card title="High volume capacity" icon="gauge-high" href="/x-api/fundamentals/high-volume-capacity">
    Handle high throughput streams
  </Card>
</CardGroup>


# Handling high-volume capacity
Source: https://docs.x.com/x-api/fundamentals/high-volume-capacity

Learn how to prepare for high-volume events when using X streaming endpoints including Filtered Stream, Volume Streams, Powerstream, and Compliance Streams.

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} theme={null}
flowchart LR
    A["Stream Connection<br/>(lightweight)"] --> B["Memory Buffer<br/>(expandable)"] --> C["Processing Thread(s)<br/>(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

<CardGroup>
  <Card title="Consuming streaming data" icon="stream" href="/x-api/fundamentals/consuming-streaming-data">
    Build robust streaming clients
  </Card>

  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Reconnect gracefully
  </Card>

  <Card title="Recovery and redundancy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055" href="/x-api/fundamentals/recovery-and-redundancy">
    Build resilient applications
  </Card>
</CardGroup>


# Metrics
Source: https://docs.x.com/x-api/fundamentals/metrics

Request public, non-public, organic, and promoted engagement metrics for Posts and video media on X API v2, including impressions, likes, and views.

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                                    |

<Note>
  **30-day limit**: Non-public, organic, and promoted metrics are only available for posts created within the last 30 days.
</Note>

***

## 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 theme={null}
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=public_metrics" \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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 theme={null}
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 title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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 theme={null}
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 title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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 theme={null}
tweet.fields=public_metrics,organic_metrics,promoted_metrics
```

***

## Metric definitions

<Accordion title="Impressions">
  Count of times the post appeared on a user's screen. Not unique—the same user viewing twice counts as two impressions.
</Accordion>

<Accordion title="Repost count">
  Number of reposts (retweets). Does not include quote posts.
</Accordion>

<Accordion title="Quote count">
  Number of quote posts (reposts with comment). These are always organic.
</Accordion>

<Accordion title="Bookmark count">
  Number of times the post has been bookmarked by users.
</Accordion>

<Accordion title="Video views">
  Aggregated across all posts containing the video. A video reposted in multiple posts has one total view count.
</Accordion>

<Accordion title="Playback quartiles">
  Number of unique users who played through each percentage of the video. Useful for understanding drop-off rates.
</Accordion>

***

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

<CardGroup>
  <Card title="Data Dictionary" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/fundamentals/data-dictionary">
    Complete field reference.
  </Card>

  <Card title="Authentication" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/resources/fundamentals/authentication/overview">
    Set up user context auth.
  </Card>
</CardGroup>


# Pagination
Source: https://docs.x.com/x-api/fundamentals/pagination

Page through X API v2 results using next_token and previous_token cursors in the meta object to retrieve every result across multiple requests.

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 theme={null}
# 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 theme={null}
{
  "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 theme={null}
{
  "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

<Tabs>
  <Tab title="Python">
    ```python title="Example" lines wrap icon="python" theme={null}
    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
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript title="Example" expandable lines wrap icon="square-js" theme={null}
    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;
    }
    ```
  </Tab>
</Tabs>

***

## Best practices

<CardGroup>
  <Card title="Use max results" icon="arrow-up-1-9">
    Request the maximum allowed `max_results` to minimize API calls.
  </Card>

  <Card title="Handle partial pages" icon="square-check">
    The last page may have fewer results than `max_results`.
  </Card>

  <Card title="Store tokens" icon="database">
    Save `next_token` if you need to resume pagination later.
  </Card>

  <Card title="Don't poll with pagination" icon="clock">
    For new data, use `since_id` instead of paginating repeatedly.
  </Card>
</CardGroup>

***

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

<CardGroup>
  <Card title="Rate limits" icon="gauge-high" href="/x-api/fundamentals/rate-limits">
    Understand request limits when paginating.
  </Card>

  <Card title="SDKs" icon="cube" href="/tools-and-libraries">
    Libraries with built-in pagination.
  </Card>
</CardGroup>


# Post Annotations
Source: https://docs.x.com/x-api/fundamentals/post-annotations

Use X API v2 entity and context annotations to identify people, places, products, organizations, and topic domains semantically inside Post text.

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 theme={null}
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=context_annotations,entities" \
  -H "Authorization: Bearer $TOKEN"
```

***

## Response structure

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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:

<Tabs>
  <Tab title="Entertainment">
    | ID | Domain      |
    | :- | :---------- |
    | 3  | TV Shows    |
    | 4  | TV Episodes |
    | 54 | Musician    |
    | 56 | Actor       |
    | 86 | Movie       |
    | 91 | Podcast     |
  </Tab>

  <Tab title="Sports">
    | ID | Domain        |
    | :- | :------------ |
    | 6  | Sports Events |
    | 11 | Sport         |
    | 12 | Sports Team   |
    | 26 | Sports League |
    | 60 | Athlete       |
    | 93 | Coach         |
  </Tab>

  <Tab title="Business & Tech">
    | ID  | Domain         |
    | :-- | :------------- |
    | 45  | Brand Vertical |
    | 46  | Brand Category |
    | 47  | Brand          |
    | 48  | Product        |
    | 165 | Technology     |
    | 166 | Stocks         |
  </Tab>

  <Tab title="Other">
    | ID  | Domain                   |
    | :-- | :----------------------- |
    | 10  | Person                   |
    | 13  | Place                    |
    | 29  | Events                   |
    | 35  | Politicians              |
    | 119 | Holiday                  |
    | 131 | Unified Twitter Taxonomy |
  </Tab>
</Tabs>

<Note>
  Domain 131 (Unified Twitter Taxonomy) powers X's Topics feature visible to users on the platform.
</Note>

***

## Using annotations in filters

### Search and filtered stream

Filter posts by context annotation entity ID:

```bash theme={null}
# Posts about a specific entity
context:86.1234567890

# Posts in a specific domain
context:86.*
```

### Practical examples

```bash theme={null}
# 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

<Warning>
  **Not all posts are annotated.** Annotation coverage depends on:

  * Language support
  * Topic coverage in X's taxonomy
  * Semantic richness of the post text
</Warning>

* 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

<CardGroup>
  <Card title="Context Entity List" icon="github" href="https://github.com/xdevplatform/twitter-context-annotations">
    CSV of available context annotation entities.
  </Card>
</CardGroup>


# Usage and Billing
Source: https://docs.x.com/x-api/fundamentals/post-cap

X API v2 uses pay-per-usage pricing. You're charged based on actual API consumption, tracked at the app level. Pay-per-usage plans are subject to a monthly.

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                |

<Note>
  Pay-per-usage plans are subject to a monthly cap of 3 million Post reads. If you need higher volume, consider an [Enterprise plan](/forms/enterprise-api-interest).
</Note>

***

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

<Note>
  **Daily deduplication**: If the same post is returned from multiple queries within a day, it only counts once for billing.
</Note>

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

<CardGroup>
  <Card title="Set budgets" icon="wallet">
    Configure spending limits in the Developer Console.
  </Card>

  <Card title="Monitor alerts" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bell.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=5e0b3dcfbb39ba3d4619931d7cd927d1">
    Get notified before hitting budget thresholds.
  </Card>

  <Card title="Use caching" icon="database">
    Cache responses to avoid re-fetching the same posts.
  </Card>

  <Card title="Optimize queries" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e">
    Use precise filters to retrieve only needed posts.
  </Card>
</CardGroup>

***

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

<CardGroup>
  <Card title="Contact Enterprise Sales" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bank.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=6dd9ad48fa88936abb112b49e022abff" href="/enterprise/forms/enterprise-api-interest">
    Discuss custom solutions for your needs.
  </Card>
</CardGroup>

***

## FAQs

<Accordion title="What happens if I run out of credits?">
  API requests will fail until you purchase more credits. Set up balance alerts to avoid interruption.
</Accordion>

<Accordion title="Are there monthly minimums?">
  No. Pay only for what you use. You can have months with zero usage and zero cost.
</Accordion>

<Accordion title="How is streaming billed?">
  Each unique post delivered through filtered stream counts toward usage, subject to daily deduplication.
</Accordion>

<Accordion title="Do failed requests count?">
  No. Only successful responses that return data are billed.
</Accordion>

***

## Next steps

<CardGroup>
  <Card title="Developer Console" icon="grid-2" href="https://console.x.com">
    View pricing and purchase credits.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/x-api/fundamentals/rate-limits">
    Understand request limits (separate from billing).
  </Card>
</CardGroup>


# X API Rate Limits
Source: https://docs.x.com/x-api/fundamentals/rate-limits

Per-endpoint X API v2 rate limits for posts, users, search, streams, and DMs, plus how to read the x-rate-limit response headers and handle 429s.

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).

<Note>
  Limits are shown per 15 minutes unless otherwise noted (e.g., "/24hrs" or "/sec").
</Note>

### 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 theme={null}
{
  "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 title="Example" lines wrap icon="python" theme={null}
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

<CardGroup>
  <Card title="Cache responses" icon="database">
    Store results locally to reduce repeated requests.
  </Card>

  <Card title="Use streaming" icon="signal-stream">
    For real-time data, use filtered stream instead of polling.
  </Card>

  <Card title="Monitor headers" icon="gauge-high">
    Track remaining requests to avoid hitting limits.
  </Card>

  <Card title="Spread requests" icon="clock">
    Distribute requests across the time window.
  </Card>
</CardGroup>

***

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

<CardGroup>
  <Card title="Error handling" icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" href="/x-api/fundamentals/response-codes-and-errors">
    Handle 429 and other errors.
  </Card>

  <Card title="Getting started" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/getting-started/about-x-api">
    Learn about access levels and features.
  </Card>
</CardGroup>


# Recovery and redundancy
Source: https://docs.x.com/x-api/fundamentals/recovery-and-redundancy

Maximize uptime on X streaming endpoints with redundant connections, automatic reconnects, and backfill or Replay to recover missed Posts and data.

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.

<Note>
  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.
</Note>

***

## 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 theme={null}
curl 'https://api.x.com/2/tweets/search/stream?backfill_minutes=5' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

**Firehose Stream:**

```bash theme={null}
curl 'https://api.x.com/2/tweets/firehose/stream?backfill_minutes=5&partition=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

<Note>
  **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
</Note>

***

## 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 theme={null}
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 theme={null}
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 theme={null}
curl 'https://api.x.com/2/powerstream?startTime=2022-07-12T15:10:00Z&endTime=2022-07-12T15:20:00Z' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

<Note>
  **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
</Note>

***

## 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.

<Warning>
  **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.
</Warning>

***

## Recovery decision tree

```mermaid actions={false} theme={null}
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

<CardGroup>
  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Detect and handle disconnections
  </Card>

  <Card title="Consuming streaming data" icon="stream" href="/x-api/fundamentals/consuming-streaming-data">
    Build robust streaming clients
  </Card>

  <Card title="High volume capacity" icon="gauge-high" href="/x-api/fundamentals/high-volume-capacity">
    Handle high throughput streams
  </Card>
</CardGroup>


# Response Codes & Errors
Source: https://docs.x.com/x-api/fundamentals/response-codes-and-errors

Reference of HTTP status codes, error response formats, and common 400, 401, 403, 404, 429, and 500 errors returned by the X API for debugging.

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](https://developer.x.com/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 theme={null}
{
  "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 title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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

<Accordion title="401 Unauthorized">
  **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)
</Accordion>

<Accordion title="403 Forbidden">
  **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
</Accordion>

<Accordion title="429 Too Many Requests">
  **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)
</Accordion>

<Accordion title="400 Bad Request">
  **Fix your request:**

  * Validate JSON syntax
  * Check for missing required parameters
  * Verify parameter types (strings vs. numbers)
  * Escape special characters in queries
</Accordion>

<Accordion title="Missing expected posts">
  **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
</Accordion>

<Accordion title="Stream disconnections">
  **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/fundamentals/handling-disconnections)
</Accordion>

***

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

<CardGroup>
  <Card title="Check status codes" icon="square-check">
    Always check HTTP status before parsing the response body.
  </Card>

  <Card title="Handle partial errors" icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca">
    Check for `errors` array even in 200 responses.
  </Card>

  <Card title="Implement retry logic" icon="arrows-rotate">
    Use exponential backoff for 429 and 5xx errors.
  </Card>

  <Card title="Log request details" icon="file-lines">
    Include request ID and timestamp for debugging.
  </Card>
</CardGroup>

***

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

<CardGroup>
  <Card title="Developer Forum" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=ce6313d8c0b7b4e5363f2ce80b89f7e4" href="https://devcommunity.x.com">
    Ask questions and search solutions.
  </Card>

  <Card title="API Status" icon="signal" href="https://developer.x.com/status">
    Check for known issues.
  </Card>
</CardGroup>


# Versioning
Source: https://docs.x.com/x-api/fundamentals/versioning

How X API versioning works, the difference between v1.1, v2, and enterprise, and which changes are considered breaking versus additive updates.

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            |

<Tip>
  Use **X API v2** for all new projects. This is where all new features ship.
</Tip>

***

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

<CardGroup>
  <Card title="Changelog" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-history.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=6afe17587c08ee621e37afde19a07ff1" href="/changelog">
    All platform changes and updates.
  </Card>

  <Card title="Forum Announcements" icon="bullhorn" href="https://devcommunity.x.com/c/announcements/22">
    Breaking change notices.
  </Card>

  <Card title="@XDevelopers" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-logo-x.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=53e3153f3b8d6efdad31484ef133b274" href="https://x.com/XDevelopers">
    Platform news and updates.
  </Card>

  <Card title="Newsletter" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-envelope.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=fbd38dbcd64d8688d3c9912ac30c4621" href="/newsletter">
    Monthly digest.
  </Card>
</CardGroup>

***

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

<CardGroup>
  <Card title="Migration overview" icon="route" href="/x-api/migrate/overview">
    Current migration guidance.
  </Card>

  <Card title="Endpoint map" icon="map" href="/x-api/migrate/x-api-endpoint-map">
    v1 to v2 endpoint mapping.
  </Card>
</CardGroup>

***

## Best practices

<CardGroup>
  <Card title="Use v2" icon="arrow-up">
    Start new projects on the latest version.
  </Card>

  <Card title="Monitor announcements" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bell.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=5e0b3dcfbb39ba3d4619931d7cd927d1">
    Subscribe to changelog and forum updates.
  </Card>

  <Card title="Test changes" icon="flask">
    Test in development before production updates.
  </Card>

  <Card title="Plan migrations" icon="calendar">
    Don't wait until deprecation to upgrade.
  </Card>
</CardGroup>


# Get OpenAPI Spec.
Source: https://docs.x.com/x-api/general/get-openapi-spec

get /2/openapi.json
Retrieves the full OpenAPI Specification in JSON format. (See https://github.com/OAI/OpenAPI-Specification/blob/master/README.md)



# About the X API
Source: https://docs.x.com/x-api/getting-started/about-x-api

High-level overview of the X API covering capabilities, v2 versus v1.1 versions, available resources, pricing tiers, and how to start building.

The X API provides programmatic access to X's public conversation. Retrieve posts, analyze trends, build integrations, and create new experiences on the platform.

***

## What you can do

| Capability             | Description                                      |
| :--------------------- | :----------------------------------------------- |
| **Read posts**         | Search, look up, and stream posts in real-time   |
| **Publish content**    | Create posts, replies, and threads               |
| **Manage users**       | Look up users, manage follows, blocks, and mutes |
| **Analyze data**       | Access metrics, trends, and engagement analytics |
| **Build integrations** | Send DMs, manage lists, and interact with Spaces |

***

## API versions

<Tabs>
  <Tab title="X API v2 (Recommended)">
    The current version of the X API with modern features and flexible pricing.

    **Why use v2:**

    * Pay-per-usage pricing
    * Modern JSON response format
    * Flexible [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions)
    * Advanced features: annotations, conversation tracking, edit history
    * All new endpoints and features

    **Getting started:**

    1. Sign up at [console.x.com](https://console.x.com)
    2. Create an app and get credentials
    3. [Make your first request](/x-api/getting-started/make-your-first-request)
  </Tab>

  <Tab title="X API v1.1 (Legacy)">
    The previous version of the X API. Limited support; use v2 for new projects.

    **Still available:**

    * Some media upload endpoints
    * Legacy streaming (deprecated)
    * Some specialized endpoints

    **Migrating to v2:**
    See the [migration guide](/x-api/migrate/overview) for endpoint mapping and data format changes.
  </Tab>
</Tabs>

***

## Available resources

The X API provides access to these resource types:

<CardGroup>
  <Card title="Posts" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f">
    Search, retrieve, create, and delete posts. Access timelines, threads, and quote posts.
  </Card>

  <Card title="Users" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305">
    Look up profiles, manage relationships, and access follower data.
  </Card>

  <Card title="Spaces" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-microphone.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=84616ff8f3d942047a71ee5e0a5adab9">
    Discover live audio conversations and participants.
  </Card>

  <Card title="Direct Messages" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-envelope.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=fbd38dbcd64d8688d3c9912ac30c4621">
    Send and receive private messages between users.
  </Card>

  <Card title="Lists" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5">
    Create and manage curated lists of accounts.
  </Card>

  <Card title="Trends" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-feather-chart-line.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=185e7e1271f798947403bb3f0c44f294">
    Access trending topics by location.
  </Card>
</CardGroup>

***

## v2 highlights

<Accordion title="Fields and expansions">
  Request only the data you need. Use `fields` parameters to select specific attributes and `expansions` to include related objects.

  ```bash theme={null}
  curl "https://api.x.com/2/tweets/123?tweet.fields=created_at,public_metrics&expansions=author_id&user.fields=username" \
    -H "Authorization: Bearer $TOKEN"
  ```

  [Learn more about fields →](/x-api/fundamentals/fields)
</Accordion>

<Accordion title="Post annotations">
  Posts include semantic annotations identifying people, places, products, and topics. Filter streams and searches by topic.

  [Learn more about annotations →](/x-api/fundamentals/post-annotations)
</Accordion>

<Accordion title="Engagement metrics">
  Access public metrics (likes, reposts, replies) and private metrics (impressions, clicks) for your own posts.

  [Learn more about metrics →](/x-api/fundamentals/metrics)
</Accordion>

<Accordion title="Conversation tracking">
  Reconstruct entire conversation threads using `conversation_id`. Track replies across the full thread.

  [Learn more about conversation tracking →](/x-api/fundamentals/conversation-id)
</Accordion>

<Accordion title="Edit history">
  Access the edit history of posts, including all previous versions and edit metadata.

  [Learn more about edit posts →](/x-api/fundamentals/edit-posts)
</Accordion>

***

## Pricing

X API v2 uses **pay-per-usage** pricing:

| Benefit                | Description                                                    |
| :--------------------- | :------------------------------------------------------------- |
| **No subscriptions**   | Pay only for what you use                                      |
| **Credit-based**       | Purchase credits, deducted per request                         |
| **Real-time tracking** | Monitor usage in the Developer Console                         |
| **Deduplication**      | Same resource requested twice in 24 hours is only charged once |

[View pricing details →](/x-api/getting-started/pricing)

***

## Next steps

<CardGroup>
  <Card title="Get access" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/x-api/getting-started/getting-access">
    Sign up and create your first app.
  </Card>

  <Card title="Make your first request" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/getting-started/make-your-first-request">
    Call the API in minutes.
  </Card>
</CardGroup>


# Getting Access
Source: https://docs.x.com/x-api/getting-started/getting-access

Sign up for a developer account, create an app, and save the API keys, bearer token, and OAuth credentials you need to start calling the X API.

Get started with the X API in three steps: sign up, create an app, and save your credentials.

<Button href="https://console.x.com">Sign up now</Button>

***

## Step 1: Create a developer account

<Steps>
  <Step title="Go to the Developer Console">
    Visit [console.x.com](https://console.x.com) and sign in with your X account.
  </Step>

  <Step title="Accept the Developer Agreement">
    Review and accept the Developer Agreement and Policy.
  </Step>

  <Step title="Complete your profile">
    Provide basic information about how you'll use the API.
  </Step>
</Steps>

***

## Step 2: Create an app

After signing up, create an app to get your API credentials:

<Steps>
  <Step title="Click 'New App'">
    From the Developer Console dashboard, create a new app.
  </Step>

  <Step title="Enter app details">
    Provide a name, description, and use case for your app.
  </Step>

  <Step title="Generate credentials">
    The console will generate your API keys and tokens.
  </Step>
</Steps>

***

## Step 3: Save your credentials

You'll receive several credentials depending on your authentication needs:

| Credential                | Purpose                                                                  |
| :------------------------ | :----------------------------------------------------------------------- |
| **API Key & Secret**      | Identify your app. Used to generate tokens and sign OAuth 1.0a requests. |
| **Bearer Token**          | App-only authentication for reading public data.                         |
| **Access Token & Secret** | Make requests on behalf of your own account (OAuth 1.0a).                |
| **Client ID & Secret**    | OAuth 2.0 authentication for user-context requests.                      |

<Warning>
  **Save immediately.** Credentials are only displayed once. Store them in a password manager or secure vault. If you lose them, you'll need to regenerate (which invalidates the old ones).
</Warning>

***

## Which credentials do you need?

<Tabs>
  <Tab title="Reading public data">
    Use the **Bearer Token** for simple, read-only access to public data.

    ```bash theme={null}
    curl "https://api.x.com/2/users/by/username/xdevelopers" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```

    Best for: Searching posts, looking up users, reading trends.
  </Tab>

  <Tab title="Acting as a user">
    Use **OAuth 2.0** (recommended) or **OAuth 1.0a** to act on behalf of users.

    OAuth 2.0 offers fine-grained scopes—request only the permissions you need.

    Best for: Posting, liking, following, accessing DMs.

    [OAuth 2.0 guide →](/resources/fundamentals/authentication/oauth-2-0/overview)
  </Tab>

  <Tab title="Acting as yourself">
    Use your **Access Token & Secret** to make requests as your own account.

    These tokens represent the account that owns the app.

    Best for: Testing, personal bots, your own automation.
  </Tab>
</Tabs>

***

## Credential security best practices

<CardGroup>
  <Card title="Use environment variables" icon="terminal">
    Never hardcode credentials in your source code.
  </Card>

  <Card title="Don't commit to git" icon="code-branch">
    Add credential files to `.gitignore`.
  </Card>

  <Card title="Rotate regularly" icon="arrows-rotate">
    Regenerate credentials periodically as a security measure.
  </Card>

  <Card title="Use minimal scopes" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-check.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=768533bde161ac68862de87449f011c3">
    Only request the OAuth permissions your app needs.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="Make your first request" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/getting-started/make-your-first-request">
    Call the API with your new credentials.
  </Card>

  <Card title="Learn about authentication" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-key.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=de93497af2dde62afd3a06e896d330f5" href="/resources/fundamentals/authentication/overview">
    Understand OAuth 1.0a and OAuth 2.0.
  </Card>
</CardGroup>


# X API pay-per-usage pricing and credits
Source: https://docs.x.com/x-api/getting-started/pricing

The X API uses pay-per-usage pricing with no subscriptions. Buy credits, set spending limits, and earn up to 20% back in free xAI API credits.

The X API uses **pay-per-usage** pricing. No subscriptions—pay only for what you use.

<Button href="https://developer.x.com/#pricing">View pricing & purchase credits</Button>

***

## How it works

<CardGroup>
  <Card title="Credit-based" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-coins.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=d8b17de3fb4032d86b77606ea95fcb55">
    Purchase credits upfront in the Developer Console. Credits are deducted as you make API requests.
  </Card>

  <Card title="Per-endpoint pricing" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219">
    Different endpoints have different costs. View current rates in the Developer Console.
  </Card>

  <Card title="No commitments" icon="unlock">
    No contracts, subscriptions, or minimum spend. Start and stop anytime.
  </Card>

  <Card title="Real-time tracking" icon="gauge-high">
    Monitor usage and costs live in the Developer Console.
  </Card>
</CardGroup>

<Tip>
  Earn free [xAI API](https://docs.x.ai) credits when you purchase X API credits—up to 20% back based on your spend. [Learn more](#free-xai-api-credits)
</Tip>

***

## 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 |
| **Like: Read**                | \$0.001 per resource |
| **Mute: Read**                | \$0.001 per resource |
| **Block: Read**               | \$0.001 per resource |
| **Profile Update: Read**      | \$0.005 per resource |

<Note>
  Pay-per-usage plans are capped at **3 million Post reads per monthly billing cycle**. If you need higher volume, upgrade to an [Enterprise plan](/forms/enterprise-api-interest).
</Note>

### Write operations

Charged per request.

| Action                       | Unit cost           |
| :--------------------------- | :------------------ |
| **Post: Create**             | \$0.015 per request |
| **Post: Create (with URL)**  | \$0.200 per request |
| **Post: Create (summoned)**  | \$0.010 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 |
| **Trends**                   | \$0.010 per request |

<Note>
  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).
</Note>

### Webhook events

Webhook events delivered through the [X Activity API](/x-api/activity/introduction) are billed per event delivered, using the same event names shown in the Activity API docs. You are charged once per billable event, deduplicated within the same 24-hour UTC window as other resources.

| Event                    | Cost per event |
| :----------------------- | :------------- |
| `post.create`            | \$0.005        |
| `post.delete`            | Not billed     |
| `follow.follow`          | \$0.010        |
| `follow.unfollow`        | \$0.010        |
| `mute.mute`              | \$0.001        |
| `mute.unmute`            | \$0.001        |
| `block.block`            | \$0.001        |
| `block.unblock`          | \$0.001        |
| `profile.update.*`       | \$0.005        |
| `chat.received`          | \$0.010        |
| `chat.sent`              | Not billed     |
| `chat.conversation_join` | Not billed     |
| `dm.received`            | \$0.010        |
| `dm.sent`                | Not billed     |
| `dm.read`                | Not billed     |
| `dm.indicate_typing`     | Not billed     |
| `news.new`               | \$0.005        |
| `spaces.start`           | \$0.005        |
| `spaces.end`             | \$0.005        |

***

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

<Tip>
  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.
</Tip>

***

## 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.

This means:

* Requesting the same Post multiple times in a day counts as one charge
* The deduplication window resets at midnight UTC
* This applies to all billable resources (Posts, users, etc.)

<Note>
  Deduplication is a **soft guarantee**. While it occurs in the vast majority of cases, there may be specific edge cases like service outages that result in resources not being deduplicated.
</Note>

***

## Credit balance

Your credit balance is displayed in the Developer Console. Credits are deducted in real-time as you make API requests.

<Warning>
  Monitor your credit balance regularly to avoid service interruptions. Add credits before your balance reaches zero to ensure uninterrupted API access.

  ***Note:** It is possible for an account credit balance to go slightly negative. In this case, API requests will be blocked until you add credits to cover the negative balance.*
</Warning>

### Auto-recharge

Enable auto-recharge to automatically top up your credit balance and avoid service interruptions. Configure this in the Developer Console:

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

#### When the trigger fires

Auto-recharge triggers the first time your balance drops below the trigger threshold after having been **at or above** it. A balance exactly equal to the threshold counts as armed: if you purchase \$5 of credits with a \$5 trigger threshold, your very first spend takes the balance below the threshold and a top-up is triggered.

<Note>
  Auto-recharge requires a saved payment method set as your default. You can cancel anytime in the Developer Console or by contacting support.
</Note>

#### Auto-recharge safeguards

To protect you from runaway or unexpectedly large charges, auto-recharge has two built-in limits:

* **One top-up per 5-minute window.** Automatic charges can trigger at most once every 5 minutes, so a sudden burst of usage cannot stack multiple recharges back-to-back.
* **Paused at zero or negative balance.** Auto-recharge does not run while your account balance is zero or negative. Add credits manually to resume automatic top-ups.

<Warning>
  If your usage is bursty enough to drain a full recharge in under 5 minutes, you can still see "out of credits" errors even with auto-recharge on. Raise your **Recharge amount** so a single top-up comfortably outlasts a 5-minute window of your peak consumption.
</Warning>

***

### Spending limits

Set a maximum amount you can spend per billing cycle to control costs. When the limit is reached, API requests will be blocked until the next billing cycle.

| Option             | Description                                                          |
| :----------------- | :------------------------------------------------------------------- |
| **Spending limit** | Set a specific dollar amount as your maximum spend per billing cycle |

<Tip>
  Use spending limits to prevent unexpected charges, especially during development and testing.
</Tip>

***

## Free xAI API credits

When you purchase X API credits, you can earn free [xAI API](https://docs.x.ai) credits based on your cumulative spend during a billing cycle.

<Note>
  To receive free xAI credits, you must link your xAI team to your X developer account. You can do this by visiting your account settings in the [developer console](https://console.x.com).
</Note>

### 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.

| Cumulative spend | Rate |
| :--------------- | :--- |
| \$0 – \$199      | 0%   |
| \$200 – \$499    | 10%  |
| \$500 – \$999    | 15%  |
| \$1,000+         | 20%  |

<Note>
  The rate applies to your **entire cumulative balance**, but you only receive the delta—what's newly owed minus what was already credited.
</Note>

### Example

Suppose you make several purchases throughout a billing cycle:

| Purchase    | Rate | Total owed | Already credited | You receive |
| :---------- | :--- | :--------- | :--------------- | :---------- |
| \$100       | 0%   | \$0        | \$0              | **\$0**     |
| \$100       | 10%  | \$20       | \$0              | **\$20**    |
| \$150       | 10%  | \$35       | \$20             | **\$15**    |
| \$150       | 15%  | \$75       | \$35             | **\$40**    |
| \$250       | 15%  | \$112.50   | \$75             | **\$37.50** |
| \$250       | 20%  | \$200      | \$112.50         | **\$87.50** |
|             |      |            |                  |             |
| **\$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.

<Tip>
  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).
</Tip>

***

## Monitoring usage

Track your API usage programmatically with the [Usage endpoint](/x-api/usage/introduction):

```bash theme={null}
curl "https://api.x.com/2/usage/tweets" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

This returns daily Post consumption counts, helping you:

* Track consumption against your budget
* Set up alerts when approaching limits
* Identify high-consumption endpoints
* Generate usage reports

***

## Next steps

<CardGroup>
  <Card title="Developer Console" icon="grid-2" href="https://console.x.com">
    Purchase credits and view current pricing.
  </Card>

  <Card title="Usage API" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143" href="/x-api/usage/introduction">
    Monitor usage programmatically.
  </Card>
</CardGroup>


# X API
Source: https://docs.x.com/x-api/introduction

Programmatic access to X with v2 REST endpoints for Posts, users, Spaces, lists, DMs, and trends, with pay-per-use pricing and modern SDKs.

The X API gives you programmatic access to X's public conversation. Read posts, publish content, manage users, and analyze trends—all through modern REST endpoints with flexible pay-per-usage pricing.

<CardGroup>
  <Card title="Get started" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/getting-started/make-your-first-request">
    Create an app and make your first request in minutes.
  </Card>

  <Card title="API reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/create-post">
    Explore all available endpoints.
  </Card>

  <Card title="SDKs" icon="cube" href="/tools-and-libraries">
    Official Python and TypeScript libraries.
  </Card>
</CardGroup>

***

## What you can build

<CardGroup>
  <Card title="Posts" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f" href="/x-api/posts/lookup/introduction">
    Search, retrieve, and publish posts. Access timelines, threads, and quote posts.
  </Card>

  <Card title="Users" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305" href="/x-api/users/lookup/introduction">
    Look up users, manage follows, blocks, and mutes.
  </Card>

  <Card title="Spaces" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-microphone.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=84616ff8f3d942047a71ee5e0a5adab9" href="/x-api/spaces/lookup/introduction">
    Find live audio conversations and their participants.
  </Card>

  <Card title="Direct Messages" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-envelope.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=fbd38dbcd64d8688d3c9912ac30c4621" href="/x-api/direct-messages/lookup/introduction">
    Send and receive private messages.
  </Card>

  <Card title="Lists" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/lists/list-lookup/introduction">
    Create and manage curated lists of accounts.
  </Card>

  <Card title="Trends" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-feather-chart-line.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=185e7e1271f798947403bb3f0c44f294" href="/x-api/trends/trends-by-woeid/introduction">
    Access trending topics by location.
  </Card>
</CardGroup>

***

## Pricing

The X API uses **pay-per-usage** pricing. No subscriptions—pay only for what you use.

<CardGroup>
  <Card title="Flexible scaling" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143">
    Start small and grow. Costs scale with your actual usage.
  </Card>

  <Card title="No commitments" icon="unlock">
    No contracts or minimum spend. Stop anytime.
  </Card>

  <Card title="Real-time tracking" icon="gauge-high">
    Monitor usage and costs live in the Developer Console.
  </Card>

  <Card title="Credit-based" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-coins.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=d8b17de3fb4032d86b77606ea95fcb55">
    Purchase credits upfront. Deducted as you use the API.
  </Card>
</CardGroup>

<Tip>
  Earn free [xAI API](https://docs.x.ai) credits when you purchase X API credits—up to 20% back based on your spend. [Learn more](/x-api/getting-started/pricing#free-xai-api-credits)
</Tip>

<div>
  <Button href="/x-api/getting-started/pricing">Pricing details</Button>
  <Button href="https://console.x.com">Purchase credits</Button>
</div>

***

## Key features

<Tabs>
  <Tab title="Data access">
    ### Rich data objects

    Access detailed, structured data for posts, users, media, and more:

    * **Posts**: Full text, metrics, entities, annotations, conversation threads
    * **Users**: Profiles, follower counts, verification status
    * **Media**: Images, videos, GIFs with metadata
    * **Polls**: Options and vote counts

    Customize responses with [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) to get exactly the data you need.
  </Tab>

  <Tab title="Near real-time streaming">
    ### Filtered stream

    Get posts delivered in near real-time as they're published. Define up to 1,000 filtering rules to receive only matching posts.

    ```bash theme={null}
    # Add a rule
    curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
      -H "Authorization: Bearer $TOKEN" \
      -d '{"add": [{"value": "from:xdevelopers"}]}'

    # Connect to stream
    curl "https://api.x.com/2/tweets/search/stream" \
      -H "Authorization: Bearer $TOKEN"
    ```

    [Learn more about filtered stream →](/x-api/posts/filtered-stream/introduction)
  </Tab>

  <Tab title="Search & analytics">
    ### Full-archive search

    Search the complete history of public posts—back to 2006. Build queries with operators for users, keywords, dates, and more.

    ```bash theme={null}
    curl "https://api.x.com/2/tweets/search/all?query=AI%20lang:en" \
      -H "Authorization: Bearer $TOKEN"
    ```

    ### Metrics

    Access engagement metrics including impressions, likes, reposts, replies, and video views.

    [Learn more about search →](/x-api/posts/search/introduction)
  </Tab>
</Tabs>

***

## Quick start

<Steps>
  <Step title="Create a developer account">
    Sign up at [console.x.com](https://console.x.com) and create an app.
  </Step>

  <Step title="Get your credentials">
    Generate your Bearer Token for app-only requests.
  </Step>

  <Step title="Make a request">
    Try looking up a user:

    ```bash theme={null}
    curl "https://api.x.com/2/users/by/username/xdevelopers" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```
  </Step>
</Steps>

<Button href="/x-api/getting-started/make-your-first-request">Full quickstart guide</Button>

***

## Tools & libraries

<CardGroup>
  <Card title="Python SDK" icon="python" href="/xdks/python/overview">
    Official Python library with async support.
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/xdks/typescript/overview">
    Official TypeScript/JavaScript library.
  </Card>

  <Card title="Postman" icon="server" href="https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80">
    Interactive API explorer.
  </Card>
</CardGroup>

[Browse all libraries →](/tools-and-libraries)

***

## Support

<CardGroup>
  <Card title="Developer Forum" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=ce6313d8c0b7b4e5363f2ce80b89f7e4" href="https://devcommunity.x.com">
    Get help from the community and X team.
  </Card>

  <Card title="Support Hub" icon="circle-question" href="https://developer.x.com/en/support/twitter-api.html">
    FAQs and troubleshooting guides.
  </Card>
</CardGroup>


# Add Lists Member
Source: https://docs.x.com/x-api/lists/add-list-member

post /2/lists/{id}/members



# Add Lists Member
Source: https://docs.x.com/x-api/lists/add-lists-member

post /2/lists/{id}/members



# Create Lists
Source: https://docs.x.com/x-api/lists/create-list

post /2/lists



# Create Lists
Source: https://docs.x.com/x-api/lists/create-lists

post /2/lists



# Delete List
Source: https://docs.x.com/x-api/lists/delete-list

delete /2/lists/{id}
Deletes a specific List owned by the authenticated user by its ID.



# Get Lists by ID
Source: https://docs.x.com/x-api/lists/get-list-by-id

get /2/lists/{id}



# Get Lists Followers
Source: https://docs.x.com/x-api/lists/get-list-followers

get /2/lists/{id}/followers



# Get Lists Members
Source: https://docs.x.com/x-api/lists/get-list-members

get /2/lists/{id}/members



# Get Lists Posts
Source: https://docs.x.com/x-api/lists/get-list-posts

get /2/lists/{id}/tweets



# Get Lists by ID
Source: https://docs.x.com/x-api/lists/get-lists-by-id

get /2/lists/{id}



# Get Lists Followers
Source: https://docs.x.com/x-api/lists/get-lists-followers

get /2/lists/{id}/followers



# Get Lists Members
Source: https://docs.x.com/x-api/lists/get-lists-members

get /2/lists/{id}/members



# Get Lists Posts
Source: https://docs.x.com/x-api/lists/get-lists-posts

get /2/lists/{id}/tweets



# Integration Guide
Source: https://docs.x.com/x-api/lists/list-lookup/integrate

This guide covers the key concepts you need to integrate the List lookup endpoints into your. Reference for the X API v2 standard tier covering list lookup.

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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/lists/84839422?\
  list.fields=description,member_count,follower_count,private" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  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 theme={null}
  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);
  ```
</CodeGroup>

***

## Endpoints overview

| Method | Endpoint                                                   | Description               |
| :----- | :--------------------------------------------------------- | :------------------------ |
| GET    | [`/2/lists/:id`](/x-api/lists/get-list-by-id)              | 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 theme={null}
{
  "data": {
    "id": "84839422",
    "name": "Tech News"
  }
}
```

### Available fields

<Accordion title="list.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 |
</Accordion>

<Accordion title="user.fields (requires owner_id expansion)">
  | Field               | Description                 |
  | :------------------ | :-------------------------- |
  | `username`          | Owner's @handle             |
  | `name`              | Owner's display name        |
  | `verified`          | Owner's verification status |
  | `profile_image_url` | Owner's avatar URL          |
</Accordion>

### Example with expansions

<CodeGroup>
  ```bash cURL theme={null}
  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 title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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
  ```
</CodeGroup>

### Response with expansion

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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
      }
    ]
  }
}
```

<Card title="Fields and expansions guide" icon="sliders" href="/x-api/fundamentals/fields">
  Learn more about customizing responses
</Card>

***

## Pagination

When retrieving owned Lists, results are paginated:

<CodeGroup>
  ```bash cURL theme={null}
  # 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 title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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`);
  ```
</CodeGroup>

<Card title="Pagination guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/fundamentals/pagination">
  Learn more about pagination
</Card>

***

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

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/lists/list-lookup/quickstart">
    Make your first List lookup request
  </Card>

  <Card title="List Posts" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/lists/list-tweets/introduction">
    Get Posts from a List
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/lists/get-list-by-id">
    Full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# List Lookup
Source: https://docs.x.com/x-api/lists/list-lookup/introduction

The List lookup endpoints let you retrieve information about Lists. Reference for the X API v2 standard tier covering list lookup.

The List lookup endpoints let you retrieve information about Lists. Look up a specific List by ID or get all Lists owned by a user.

## Overview

<CardGroup>
  <Card title="By ID" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5">
    Get details for a specific List
  </Card>

  <Card title="By owner" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305">
    Get all Lists owned by a user
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                                   | Description               |
| :----- | :--------------------------------------------------------- | :------------------------ |
| GET    | [`/2/lists/:id`](/x-api/lists/get-list-by-id)              | Get List by ID            |
| GET    | [`/2/users/:id/owned_lists`](/x-api/users/get-owned-lists) | Get Lists owned by a user |

***

## Response fields

By default, the response includes `id` and `name`. Request additional fields:

| Field            | Description             |
| :--------------- | :---------------------- |
| `description`    | List description        |
| `owner_id`       | Owner's user ID         |
| `private`        | Whether List is private |
| `follower_count` | Number of followers     |
| `member_count`   | Number of members       |
| `created_at`     | List creation date      |

### Example request

```bash theme={null}
curl "https://api.x.com/2/lists/1234567890?\
list.fields=description,owner_id,member_count,follower_count" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/lists/list-lookup/quickstart">
    Make your first List lookup request
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/lists/list-lookup/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/lists/list-lookup-by-list-id">
    Full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# List lookup migration overview
Source: https://docs.x.com/x-api/lists/list-lookup/migrate/overview

Compare Standard v1.1 lists/show and lists/list with X API v2 List lookup endpoints, including new fields, expansions, and authentication options.

## 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<br /><br />App only                                                                                            | OAuth 1.0a User Context<br /><br />OAuth 2.0 Authorization Code with PKCE<br /><br />App only                                           |
| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min with OAuth 1.0a<br /><br />75 requests per 15min with OAuth 2.0<br /><br />75 requests per 15 min with App only | 75 requests per 15 min with OAuth 1.0a<br /><br />75 requests per 15 min with OAuth 2.0<br /><br />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<br /><br />App only                                            | OAuth 1.0a User Context<br /><br />OAuth 2.0 Authorization Code with PKCE<br /><br />App only                                          |
| Default request [rate limits](/resources/fundamentals/rate-limits) | 15 requests per 15 min with OAuth 1.0a<br /><br />15 requests per 15 min with App only | 15 requests per 15 min with OAuth 1.0a<br /><br />15 requests per 15min with OAuth 2.0<br /><br />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.

<div>
  <Button href="/x-api/lists/list-lookup/introduction">
    Quick start
  </Button>

  <Button href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Sample code
  </Button>

  <Button href="https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80">
    Run in Postman
  </Button>
</div>


# List lookup: Standard v1.1 to X API v2
Source: https://docs.x.com/x-api/lists/list-lookup/migrate/standard-to-twitter-api-v2

Step-by-step comparison of Standard v1.1 List lookup endpoints and the X API v2 equivalents, including parameters, authentication, and rate limits.

### 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<br /><br />75 requests per 15-minute window with OAuth 1.0a User Context<br /><br />75 requests per 15-minute window with App only      | /2/lists/:id<br /><br />75 requests per 15-minute window with OAuth 1.0a User Context<br /><br />75 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE                                                                        |
| /1.1/lists/ownerships.json<br /><br />15 requests per 15-minute window with OAuth 1.0a User Context<br /><br />15 requests per 15-minute window with App only | /2/users/:id/owned\_lists<br /><br />15 requests per 15-minute window with OAuth 1.0a User Context<br /><br />15 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE<br /><br />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](https://api.x.com/1.1/lists/show.json)
    (Lookup a specified List)
  * GET [https://api.x.com/1.1/lists/ownerships.json](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](https://api.x.com/2/lists/:id)
    (Lookup a specified List)

  * GET [https://api.x.com/2/users/:id/owned\_lists](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/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/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. 

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


# Quickstart
Source: https://docs.x.com/x-api/lists/list-lookup/quickstart

This guide walks you through looking up List information using the List lookup endpoints. Reference for the X API v2 standard tier covering list lookup.

This guide walks you through looking up List information using the List lookup endpoints.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token
</Note>

***

## Get a List by ID

Retrieve details for a specific List:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/lists/1234567890?\
  list.fields=description,owner_id,member_count,follower_count,private,created_at" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get a List by ID
  response = client.lists.get(
      "1234567890",
      list_fields=["description", "owner_id", "member_count", "follower_count", "private", "created_at"]
  )

  print(f"List: {response.data.name}")
  print(f"Members: {response.data.member_count}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get a List by ID
  const response = await client.lists.get("1234567890", {
    listFields: ["description", "owner_id", "member_count", "follower_count", "private", "created_at"],
  });

  console.log(`List: ${response.data?.name}`);
  console.log(`Members: ${response.data?.member_count}`);
  ```
</CodeGroup>

### Response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "id": "1234567890",
    "name": "Tech News",
    "description": "Top tech journalists and publications",
    "owner_id": "2244994945",
    "private": false,
    "member_count": 50,
    "follower_count": 1250,
    "created_at": "2023-01-15T10:00:00.000Z"
  }
}
```

***

## Get Lists owned by a user

Retrieve all Lists owned by a specific user:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/2244994945/owned_lists?\
  list.fields=description,member_count,follower_count&\
  max_results=100" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get Lists owned by a user with pagination
  for page in client.lists.get_owned_lists(
      "2244994945",
      list_fields=["description", "member_count", "follower_count"],
      max_results=100
  ):
      for lst in page.data:
          print(f"{lst.name} - {lst.member_count} members")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get Lists owned by a user with pagination
  const paginator = client.lists.getOwnedLists("2244994945", {
    listFields: ["description", "member_count", "follower_count"],
    maxResults: 100,
  });

  for await (const page of paginator) {
    page.data?.forEach((lst) => {
      console.log(`${lst.name} - ${lst.member_count} members`);
    });
  }
  ```
</CodeGroup>

### Response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "1234567890",
      "name": "Tech News",
      "description": "Top tech journalists",
      "member_count": 50,
      "follower_count": 1250
    },
    {
      "id": "9876543210",
      "name": "Developer Tools",
      "description": "Useful tools for developers",
      "member_count": 25,
      "follower_count": 500
    }
  ],
  "meta": {
    "result_count": 2
  }
}
```

***

## Include owner information

Expand the owner's user data:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/lists/1234567890?\
  list.fields=description,owner_id&\
  expansions=owner_id&\
  user.fields=username,verified" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get List with owner info
  response = client.lists.get(
      "1234567890",
      list_fields=["description", "owner_id"],
      expansions=["owner_id"],
      user_fields=["username", "verified"]
  )

  print(f"List: {response.data.name}")
  # Owner info is in response.includes.users
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get List with owner info
  const response = await client.lists.get("1234567890", {
    listFields: ["description", "owner_id"],
    expansions: ["owner_id"],
    userFields: ["username", "verified"],
  });

  console.log(`List: ${response.data?.name}`);
  // Owner info is in response.includes?.users
  ```
</CodeGroup>

### Response with expansion

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "id": "1234567890",
    "name": "Tech News",
    "description": "Top tech journalists",
    "owner_id": "2244994945"
  },
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "username": "XDevelopers",
        "verified": true
      }
    ]
  }
}
```

***

## Available fields

| Field            | Description             |
| :--------------- | :---------------------- |
| `description`    | List description        |
| `owner_id`       | Owner's user ID         |
| `private`        | Whether List is private |
| `member_count`   | Number of members       |
| `follower_count` | Number of followers     |
| `created_at`     | List creation date      |

***

## Next steps

<CardGroup>
  <Card title="List Posts" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/lists/list-tweets/quickstart">
    Get Posts from a List
  </Card>

  <Card title="List members" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980" href="/x-api/lists/list-members/quickstart/list-members-lookup">
    Get List members
  </Card>

  <Card title="Manage Lists" icon="pen" href="/x-api/lists/manage-lists/quickstart">
    Create and update Lists
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/lists/list-lookup-by-list-id">
    Full endpoint documentation
  </Card>
</CardGroup>


# Integration guide
Source: https://docs.x.com/x-api/lists/list-members/integrate

This page covers tools and key concepts for integrating the List members endpoints. Reference for the X API v2 standard tier covering list members.

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 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/reference#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)


# List Members
Source: https://docs.x.com/x-api/lists/list-members/introduction

The List Members endpoints let you view List members, add members to your Lists, and remove. Reference for the X API v2 standard tier covering list members.

The List Members endpoints let you view List members, add members to your Lists, and remove them. You can also see which Lists a user is a member of.

## Overview

<CardGroup>
  <Card title="View members" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980">
    Get all members of a List
  </Card>

  <Card title="Add member" icon="user-plus">
    Add a user to your List
  </Card>

  <Card title="Remove member" icon="user-minus">
    Remove a user from your List
  </Card>

  <Card title="Memberships" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5">
    See Lists a user is on
  </Card>
</CardGroup>

***

## Endpoints

### List members lookup

| Method | Endpoint                                                             | Description            |
| :----- | :------------------------------------------------------------------- | :--------------------- |
| GET    | [`/2/lists/:id/members`](/x-api/lists/get-list-members)              | Get members of a List  |
| GET    | [`/2/users/:id/list_memberships`](/x-api/users/get-list-memberships) | Get Lists a user is on |

### Manage List members

| Method | Endpoint                                                           | Description     |
| :----- | :----------------------------------------------------------------- | :-------------- |
| POST   | [`/2/lists/:id/members`](/x-api/lists/add-list-member)             | Add a member    |
| DELETE | [`/2/lists/:id/members/:user_id`](/x-api/lists/remove-list-member) | Remove a member |

***

## Example: Get List members

```bash theme={null}
curl "https://api.x.com/2/lists/1234567890/members?\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

## Example: Add a member

```bash theme={null}
curl -X POST "https://api.x.com/2/lists/1234567890/members" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "9876543210"}'
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Lookup quickstart" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980" href="/x-api/lists/list-members/quickstart/list-members-lookup">
    Get members of a List
  </Card>

  <Card title="Manage quickstart" icon="user-plus" href="/x-api/lists/list-members/quickstart/manage-list-members">
    Add and remove members
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/lists/list-members/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/lists/get-list-members">
    Full endpoint documentation
  </Card>
</CardGroup>


# List members lookup
Source: https://docs.x.com/x-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2

If you have been working with the standard v1.1 GET lists/members and GET lists/memberships. Reference for the X API v2 standard tier covering migrate.

### 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](https://api.x.com/1.1/lists/members.json)
    (Lookup members of a specified List)
  * GET [https://api.x.com/1.1/lists/mem](https://api.x.com/1.1/lists/mem)


# Manage List members: v1.1 to X API v2
Source: https://docs.x.com/x-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2

Migrate add, remove, and manage List member operations from Standard v1.1 lists/members endpoints to the X API v2 manage List members endpoints.

### 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](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](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](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](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<br /><br />none  | /2/lists/:id/members<br /><br />300 requests per 15-minute window with OAuth 1.0a User Context<br /><br />300 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE           |
| /1.1/lists/members/destroy.json<br /><br />none | /2/lists/:id/members/:user\_id<br /><br />300 requests per 15-minute window with OAuth 1.0a User Context<br /><br />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 |


# List members migration overview
Source: https://docs.x.com/x-api/lists/list-members/migrate/overview

Compare Standard v1.1 List members endpoints with X API v2 List members lookup and manage List members endpoints for migration planning.

## 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<br /><br />App only                                            | OAuth 1.0a User Context<br /><br />OAuth 2.0 Authorization Code with PKCE<br /><br />App only                                              |
| Default request [rate limits](/resources/fundamentals/rate-limits) | 900 requests per 15 min with OAuth 1.0a<br /><br />75 requests per 15min with App only | 900 requests per 15 min with OAuth 1.0a<br /><br />900 requests per 15 min with OAuth 2.0<br /><br />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<br /><br />App only                                           | OAuth 1.0a User Context<br /><br />OAuth 2.0 Authorization Code with PKCE<br /><br />App only                                          |
| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min with OAuth 1.0a<br /><br />75 requests per 15min with App only | 75 requests per 15 min with OAuth 1.0a<br /><br />75 requests per 15 min with OAuth 2.0<br /><br />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) | [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<br /><br />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) | [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<br /><br />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.

<div>
  <Button href="/x-api/lists/list-members/quickstart/overview">
    Quick start
  </Button>

  <Button href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Sample code
  </Button>

  <Button href="https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80">
    Run in Postman
  </Button>
</div>


# List Members Lookup
Source: https://docs.x.com/x-api/lists/list-members/quickstart/list-members-lookup

Quickstart for retrieving the members of an X List with the X API v2 List members lookup endpoint, including authentication and sample requests.

This guide walks you through retrieving members of a List.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token
</Note>

***

## Get List members

<Steps>
  <Step title="Find the List ID">
    You can find the List ID in the URL when viewing a List:

    ```
    https://x.com/i/lists/84839422
                          └── This is the List ID
    ```
  </Step>

  <Step title="Request the List members">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/lists/84839422/members?\
      user.fields=created_at,username,verified&\
      max_results=100" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Get List members with pagination
      for page in client.lists.get_members(
          "84839422",
          user_fields=["created_at", "username", "verified"],
          max_results=100
      ):
          for user in page.data:
              print(f"{user.username} - Joined: {user.created_at}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Get List members with pagination
      const paginator = client.lists.getMembers("84839422", {
        userFields: ["created_at", "username", "verified"],
        maxResults: 100,
      });

      for await (const page of paginator) {
        page.data?.forEach((user) => {
          console.log(`${user.username} - Joined: ${user.created_at}`);
        });
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": [
        {
          "id": "1319036828964454402",
          "name": "Birdwatch",
          "username": "birdwatch",
          "created_at": "2020-10-21T22:04:47.000Z",
          "verified": true
        },
        {
          "id": "1065249714214457345",
          "name": "Spaces",
          "username": "TwitterSpaces",
          "created_at": "2018-11-21T14:24:58.000Z",
          "verified": true
        }
      ],
      "meta": {
        "result_count": 2,
        "next_token": "5349804505549807616"
      }
    }
    ```
  </Step>
</Steps>

***

## Include additional data

Use expansions to get related data like pinned Posts:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/lists/84839422/members?\
  user.fields=created_at&\
  expansions=pinned_tweet_id&\
  tweet.fields=created_at" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get List members with expansions
  for page in client.lists.get_members(
      "84839422",
      user_fields=["created_at"],
      expansions=["pinned_tweet_id"],
      tweet_fields=["created_at"]
  ):
      for user in page.data:
          print(f"{user.username}")
      # Pinned Posts are in page.includes.tweets
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get List members with expansions
  const paginator = client.lists.getMembers("84839422", {
    userFields: ["created_at"],
    expansions: ["pinned_tweet_id"],
    tweetFields: ["created_at"],
  });

  for await (const page of paginator) {
    page.data?.forEach((user) => {
      console.log(user.username);
    });
    // Pinned Posts are in page.includes?.tweets
  }
  ```
</CodeGroup>

***

## Next steps

<CardGroup>
  <Card title="Manage List members" icon="user-plus" href="/x-api/lists/list-members/quickstart/manage-list-members">
    Add and remove members
  </Card>

  <Card title="List lookup" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/lists/list-lookup/quickstart">
    Get List details
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/lists/get-list-members">
    Full endpoint documentation
  </Card>
</CardGroup>


# Manage List Members
Source: https://docs.x.com/x-api/lists/list-members/quickstart/manage-list-members

This guide walks you through adding and removing members from a List. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through adding and removing members from a List.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
  * A List that you own
</Note>

***

## Add a member to a List

<Steps>
  <Step title="Get the List ID and user ID">
    You need the ID of your List and the user ID of the person you want to add. Find user IDs using the [user lookup endpoint](/x-api/users/lookup/introduction).
  </Step>

  <Step title="Add the member">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/lists/1441162269824405510/members" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"user_id": "2244994945"}'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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)

      # Add a member to a List
      response = client.lists.add_member(
          list_id="1441162269824405510",
          user_id="2244994945"
      )

      print(f"Is member: {response.data.is_member}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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 });

      // Add a member to a List
      const response = await client.lists.addMember("1441162269824405510", {
        userId: "2244994945",
      });

      console.log(`Is member: ${response.data?.is_member}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": {
        "is_member": true
      }
    }
    ```
  </Step>
</Steps>

***

## Remove a member from a List

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.x.com/2/lists/1441162269824405510/members/2244994945" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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)

  # Remove a member from a List
  response = client.lists.remove_member(
      list_id="1441162269824405510",
      user_id="2244994945"
  )

  print(f"Is member: {response.data.is_member}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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 });

  // Remove a member from a List
  const response = await client.lists.removeMember(
    "1441162269824405510",
    "2244994945"
  );

  console.log(`Is member: ${response.data?.is_member}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "is_member": false
  }
}
```

***

## Important notes

<Note>
  * You can only manage members of Lists you own
  * Adding a user to a List does not require their permission
  * Users can see which public Lists they've been added to
</Note>

***

## Next steps

<CardGroup>
  <Card title="List members lookup" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980" href="/x-api/lists/list-members/quickstart/list-members-lookup">
    Get List members
  </Card>

  <Card title="Manage Lists" icon="pen" href="/x-api/lists/manage-lists/quickstart">
    Create and update Lists
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/lists/add-list-member">
    Full endpoint documentation
  </Card>
</CardGroup>


# List Members Overview
Source: https://docs.x.com/x-api/lists/list-members/quickstart/overview

The List members endpoints let you look up members of a List and manage List membership. Reference for the X API v2 standard tier covering quickstart.

The List members endpoints let you look up members of a List and manage List membership.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token (for lookups)
  * User Access Token (for managing members)
</Note>

***

## Available endpoints

<CardGroup>
  <Card title="List members lookup" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980" href="/x-api/lists/list-members/quickstart/list-members-lookup">
    Get members of a List
  </Card>

  <Card title="Manage List members" icon="user-plus" href="/x-api/lists/list-members/quickstart/manage-list-members">
    Add and remove members
  </Card>
</CardGroup>

***

## Authentication

| Operation          | Authentication                              |
| :----------------- | :------------------------------------------ |
| Look up members    | Bearer Token, OAuth 1.0a, or OAuth 2.0 PKCE |
| Add/remove members | OAuth 1.0a or OAuth 2.0 PKCE                |

***

## Quick example

<CodeGroup>
  ```bash cURL theme={null}
  # Get List members
  curl "https://api.x.com/2/lists/84839422/members" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get List members
  for page in client.lists.get_members("84839422"):
      for user in page.data:
          print(f"{user.username}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get List members
  const paginator = client.lists.getMembers("84839422");

  for await (const page of paginator) {
    page.data?.forEach((user) => {
      console.log(user.username);
    });
  }
  ```
</CodeGroup>

***

## Next steps

<CardGroup>
  <Card title="List lookup" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/lists/list-lookup/quickstart">
    Get List details
  </Card>

  <Card title="List Posts" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f" href="/x-api/lists/list-tweets/quickstart">
    Get Posts from a List
  </Card>
</CardGroup>


# Integration guide
Source: https://docs.x.com/x-api/lists/list-tweets/integrate

This page covers tools and key concepts for integrating the List Posts lookup endpoint. Reference for the X API v2 standard tier covering list tweets.

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

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


# List Posts
Source: https://docs.x.com/x-api/lists/list-tweets/introduction

The List Posts endpoint lets you retrieve Posts from a List's timeline. Reference for the X API v2 standard tier covering list tweets.

The List Posts endpoint lets you retrieve Posts from a List's timeline. Get the latest Posts from all members of a List.

## Overview

<CardGroup>
  <Card title="List timeline" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5">
    Get Posts from List members
  </Card>

  <Card title="Curated feed" icon="stream">
    Access your curated content feeds
  </Card>
</CardGroup>

***

## Endpoint

| Method | Endpoint                                             | Description           |
| :----- | :--------------------------------------------------- | :-------------------- |
| GET    | [`/2/lists/:id/tweets`](/x-api/lists/get-list-posts) | Get Posts from a List |

***

## Example request

```bash theme={null}
curl "https://api.x.com/2/lists/1234567890/tweets?\
tweet.fields=created_at,author_id,public_metrics&\
expansions=author_id&\
user.fields=username&\
max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/lists/list-tweets/quickstart">
    Get Posts from a List
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/lists/list-tweets/integrate">
    Key concepts and best practices
  </Card>

  <Card title="List lookup" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/lists/list-lookup/introduction">
    Get List details
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/lists/get-list-posts">
    Full endpoint documentation
  </Card>
</CardGroup>


# List Posts endpoint migration overview
Source: https://docs.x.com/x-api/lists/list-tweets/migrate/overview

Compare Standard v1.1 lists/statuses with the X API v2 List Posts endpoint, including parameters, authentication, and pagination differences.

## 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<br /><br />App only                                             | OAuth 1.0a User Context<br /><br />OAuth 2.0 Authorization Code with PKCE<br /><br />App only                                              |
| Default request [rate limits](/resources/fundamentals/rate-limits) | 900 requests per 15 min with OAuth 1.0a<br /><br />900 requests per 15min with App only | 900 requests per 15 min with OAuth 1.0a<br /><br />900 requests per 15 min with OAuth 2.0<br /><br />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.

<div>
  <Button href="/x-api/lists/list-tweets/quickstart">
    Quick start
  </Button>

  <Button href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Sample code
  </Button>

  <Button href="https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80">
    Run in Postman
  </Button>
</div>


# v1 to v2
Source: https://docs.x.com/x-api/lists/list-tweets/migrate/standard-to-twitter-api-v2

If you have been working with the standard v1.1 GET lists/statuses endpoint, the goal of this. Reference for the X API v2 standard tier covering migrate.

### 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<br /><br />900 requests per 15-minute window with OAuth 1.0a User Context<br /><br />900 requests per 15-minute window with App only | /2/lists/:id/tweets<br /><br />900 requests per 15-minute window with OAuth 1.0a User Context<br /><br />900 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE<br /><br />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](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](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/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/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.

* 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)

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/lists/84839422/tweets?tweet.fields=created_at,public_metrics&max_results=100" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python" lines wrap icon="python" theme={null}
  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 title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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)}...`);
    });
  }
  ```
</CodeGroup>


# Quickstart
Source: https://docs.x.com/x-api/lists/list-tweets/quickstart

This guide walks you through retrieving Posts from a List timeline. Reference for the X API v2 standard tier covering list tweets.

This guide walks you through retrieving Posts from a List timeline.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token
</Note>

***

<Steps>
  <Step title="Find a List ID" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5">
    You can find a List ID in the URL when viewing a List on x.com:

    ```
    https://x.com/i/lists/84839422
                          └── This is the List ID
    ```
  </Step>

  <Step title="Request the List timeline" icon="terminal">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/lists/84839422/tweets?\
      tweet.fields=created_at,public_metrics,author_id&\
      expansions=author_id&\
      user.fields=username,verified&\
      max_results=10" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Get Posts from a List with pagination
      for page in client.lists.get_tweets(
          "84839422",
          tweet_fields=["created_at", "public_metrics", "author_id"],
          expansions=["author_id"],
          user_fields=["username", "verified"],
          max_results=10
      ):
          for post in page.data:
              print(f"{post.text[:50]}... - Likes: {post.public_metrics.like_count}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Get Posts from a List with pagination
      const paginator = client.lists.getTweets("84839422", {
        tweetFields: ["created_at", "public_metrics", "author_id"],
        expansions: ["author_id"],
        userFields: ["username", "verified"],
        maxResults: 10,
      });

      for await (const page of paginator) {
        page.data?.forEach((post) => {
          console.log(`${post.text?.slice(0, 50)}... - Likes: ${post.public_metrics?.like_count}`);
        });
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response" icon="eye">
    ```json theme={null}
    {
      "data": [
        {
          "id": "1458172421115101189",
          "text": "Check out our latest announcement...",
          "author_id": "4172587277",
          "created_at": "2024-01-15T10:30:00.000Z",
          "public_metrics": {
            "retweet_count": 42,
            "reply_count": 5,
            "like_count": 156,
            "quote_count": 3
          },
          "edit_history_tweet_ids": ["1458172421115101189"]
        }
      ],
      "includes": {
        "users": [
          {
            "id": "4172587277",
            "username": "TechNews",
            "verified": true
          }
        ]
      },
      "meta": {
        "result_count": 1,
        "next_token": "7140dibdnow9c7btw3z2vwioavpvutgzrzm9icis4ndix"
      }
    }
    ```
  </Step>

  <Step title="Paginate through results" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e">
    The SDKs handle pagination automatically. For cURL, use the `next_token` from the response to get more Posts:

    ```bash theme={null}
    curl "https://api.x.com/2/lists/84839422/tweets?\
    max_results=10&\
    pagination_token=7140dibdnow9c7btw3z2vwioavpvutgzrzm9icis4ndix" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```
  </Step>
</Steps>

<Note>
  This endpoint returns up to 800 of the most recent Posts from the List.
</Note>

***

## Next steps

<CardGroup>
  <Card title="List lookup" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/lists/list-lookup/quickstart">
    Get List details
  </Card>

  <Card title="List members" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980" href="/x-api/lists/list-members/introduction">
    Get List members
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/lists/list-tweets/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/lists/get-list-posts">
    Full endpoint documentation
  </Card>
</CardGroup>


# Integration guide
Source: https://docs.x.com/x-api/lists/manage-lists/integrate

This page covers tools and key concepts for integrating the Lists endpoints. Reference for the X API v2 standard tier covering manage lists.

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

<CodeGroup>
  ```bash cURL theme={null}
  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 title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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);
  ```
</CodeGroup>

#### Update a List

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.x.com/2/lists/123456789" \
    -H "Authorization: OAuth ..." \
    -H "Content-Type: application/json" \
    -d '{"name": "Updated List Name"}'
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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);
  ```
</CodeGroup>


# Manage Lists
Source: https://docs.x.com/x-api/lists/manage-lists/introduction

Use the X API v2 Manage Lists endpoints to create, update, and delete X Lists on behalf of authenticated users and organize accounts into curated timelines.

The Manage Lists endpoints let you create, update, and delete Lists on behalf of authenticated users.

## Overview

<CardGroup>
  <Card title="Create" icon="plus">
    Create a new List
  </Card>

  <Card title="Update" icon="pen">
    Update List name and description
  </Card>

  <Card title="Delete" icon="trash">
    Delete a List
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                   | Description       |
| :----- | :----------------------------------------- | :---------------- |
| POST   | [`/2/lists`](/x-api/lists/create-list)     | Create a new List |
| PUT    | [`/2/lists/:id`](/x-api/lists/update-list) | Update a List     |
| DELETE | [`/2/lists/:id`](/x-api/lists/delete-list) | Delete a List     |

***

## Example: Create a List

```bash theme={null}
curl -X POST "https://api.x.com/2/lists" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech News",
    "description": "My favorite tech journalists",
    "private": false
  }'
```

## Example response

```json theme={null}
{
  "data": {
    "id": "1234567890",
    "name": "Tech News"
  }
}
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * User Access Tokens via [OAuth 2.0 PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/lists/manage-lists/quickstart">
    Create your first List
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/lists/manage-lists/integrate">
    Key concepts and best practices
  </Card>

  <Card title="List members" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980" href="/x-api/lists/list-members/introduction">
    Add and remove members
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/lists/create-list">
    Full endpoint documentation
  </Card>
</CardGroup>


# Manage Lists migration overview
Source: https://docs.x.com/x-api/lists/manage-lists/migrate/overview

Move List creation, updates, and deletion from Standard v1.1 lists endpoints to the X API v2 manage Lists endpoints with mapped parameters and limits.

## 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) | [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) | [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) | [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.

<div>
  <Button href="/x-api/lists/manage-lists/quickstart">
    Quick start
  </Button>

  <Button href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Sample code
  </Button>

  <Button href="https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80">
    Run in Postman
  </Button>
</div>


# v1 to v2
Source: https://docs.x.com/x-api/lists/manage-lists/migrate/standard-to-twitter-api-v2

If you have been working with the standard v1.1 POST lists/create, POST lists/destroy, and POST. Reference for the X API v2 standard tier covering migrate.

### 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](https://api.x.com/1.1/lists/create.json)
    (Creates a List)
  * POST [https://api.x.com/1.1/lists/destroy.json](https://api.x.com/1.1/lists/destroy.json)
    (Deletes a List)
  * POST [https://api.x.com/1.1/lists/update.json](https://api.x.com/1.1/lists/update.json)
    (Updates a List)
* X API v2 endpoint:
  * POST [https://api.x.com/2/lists](https://api.x.com/2/lists)
    (Creates a List)

  * DELETE [https://api.x.com/2/lists/:id](https://api.x.com/2/lists/:id)
    (Deletes a List)

  * PUT [https://api.x.com/2/lists/:id](https://api.x.com/2/lists/:id)
    (Updates a List)

**Rate limits**

\| **Standard v1**


# Quickstart
Source: https://docs.x.com/x-api/lists/manage-lists/quickstart

This guide walks you through creating, updating, and deleting Lists. Reference for the X API v2 standard tier covering manage lists.

This guide walks you through creating, updating, and deleting Lists.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Create a List

<Steps>
  <Step title="Prepare your request">
    Define the List name (required) and optional description and privacy settings:

    ```json theme={null}
    {
      "name": "Tech News",
      "description": "Top tech journalists and publications",
      "private": false
    }
    ```
  </Step>

  <Step title="Send the request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/lists" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "Tech News",
          "description": "Top tech journalists and publications",
          "private": false
        }'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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="Tech News",
          description="Top tech journalists and publications",
          private=False
      )

      print(f"List created: {response.data.id} - {response.data.name}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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: "Tech News",
        description: "Top tech journalists and publications",
        private: false,
      });

      console.log(`List created: ${response.data?.id} - ${response.data?.name}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": {
        "id": "1441162269824405510",
        "name": "Tech News"
      }
    }
    ```

    Save the `id` to update or delete the List later.
  </Step>
</Steps>

***

## Update a List

Modify a List's name, description, or privacy:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.x.com/2/lists/1441162269824405510" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Tech News & Insights",
      "description": "Updated description"
    }'
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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(
      "1441162269824405510",
      name="Tech News & Insights",
      description="Updated description"
  )

  print(f"Updated: {response.data.updated}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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("1441162269824405510", {
    name: "Tech News & Insights",
    description: "Updated description",
  });

  console.log(`Updated: ${response.data?.updated}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "updated": true
  }
}
```

***

## Delete a List

<Steps>
  <Step title="Get the List ID">
    You need the ID of the List you want to delete.
  </Step>

  <Step title="Send the delete request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X DELETE "https://api.x.com/2/lists/1441162269824405510" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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("1441162269824405510")
      print(f"Deleted: {response.data.deleted}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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("1441162269824405510");
      console.log(`Deleted: ${response.data?.deleted}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Confirm deletion">
    ```json theme={null}
    {
      "data": {
        "deleted": true
      }
    }
    ```
  </Step>
</Steps>

<Warning>
  You can only delete Lists that you own.
</Warning>

***

## Next steps

<CardGroup>
  <Card title="List members" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980" href="/x-api/lists/list-members/introduction">
    Add and remove List members
  </Card>

  <Card title="List lookup" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/lists/list-lookup/quickstart">
    Retrieve List details
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/lists/manage-lists/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/lists/create-list">
    Full endpoint documentation
  </Card>
</CardGroup>


# Integration guide
Source: https://docs.x.com/x-api/lists/pinned-lists/integrate

This page covers tools and key concepts for integrating the pinned Lists endpoints. Reference for the X API v2 standard tier covering pinned lists.

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

| Endpoint                   | Fields                       | Expansions |
| :------------------------- | :--------------------------- | :--------- |
| /2/users/:id/pinned\_lists | `list.fields`, `user.fields` | `owner_id` |


# Pinned Lists
Source: https://docs.x.com/x-api/lists/pinned-lists/introduction

The Pinned Lists endpoints let you view, pin, and unpin Lists for the authenticated user. Reference for the X API v2 standard tier covering pinned lists.

The Pinned Lists endpoints let you view, pin, and unpin Lists for the authenticated user. Pinned Lists appear prominently in the user's X interface.

## Overview

<CardGroup>
  <Card title="View pinned" icon="thumbtack">
    Get user's pinned Lists
  </Card>

  <Card title="Pin List" icon="plus">
    Pin a List
  </Card>

  <Card title="Unpin List" icon="minus">
    Unpin a List
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                                        | Description      |
| :----- | :-------------------------------------------------------------- | :--------------- |
| GET    | [`/2/users/:id/pinned_lists`](/x-api/users/get-pinned-lists)    | Get pinned Lists |
| POST   | [`/2/users/:id/pinned_lists`](/x-api/users/pin-list)            | Pin a List       |
| DELETE | [`/2/users/:id/pinned_lists/:list_id`](/x-api/users/unpin-list) | Unpin a List     |

***

## Example: Get pinned Lists

```bash theme={null}
curl "https://api.x.com/2/users/123456789/pinned_lists?\
list.fields=name,description,member_count" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
```

## Example: Pin a List

```bash theme={null}
curl -X POST "https://api.x.com/2/users/123456789/pinned_lists" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"list_id": "9876543210"}'
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * User Access Tokens via [OAuth 2.0 PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2)
</Note>

<CardGroup>
  <Card title="Lookup quickstart" icon="thumbtack" href="/x-api/lists/pinned-lists/quickstart/pinned-list-lookup">
    Get pinned Lists
  </Card>

  <Card title="Manage quickstart" icon="plus" href="/x-api/lists/pinned-lists/quickstart/manage-pinned-lists">
    Pin and unpin Lists
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/lists/pinned-lists/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-pinned-lists">
    Full endpoint documentation
  </Card>
</CardGroup>


# Manage Pinned Lists
Source: https://docs.x.com/x-api/lists/pinned-lists/quickstart/manage-pinned-lists

Quickstart for pinning and unpinning X Lists on the authenticated user account using the X API v2 pinned Lists endpoints, with example requests.

This guide walks you through pinning and unpinning Lists.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Pin a List

<Steps>
  <Step title="Get your user ID and the List ID">
    You need your authenticated user's ID and the ID of the List you want to pin. Find List IDs in the URL when viewing a List.
  </Step>

  <Step title="Pin the List">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/users/2244994945/pinned_lists" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"list_id": "1454155907651158017"}'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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)

      # Pin a List
      response = client.lists.pin(
          user_id="2244994945",
          list_id="1454155907651158017"
      )

      print(f"Pinned: {response.data.pinned}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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 });

      // Pin a List
      const response = await client.lists.pin("2244994945", {
        listId: "1454155907651158017",
      });

      console.log(`Pinned: ${response.data?.pinned}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": {
        "pinned": true
      }
    }
    ```
  </Step>
</Steps>

***

## Unpin a List

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.x.com/2/users/2244994945/pinned_lists/1454155907651158017" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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)

  # Unpin a List
  response = client.lists.unpin(
      user_id="2244994945",
      list_id="1454155907651158017"
  )

  print(f"Pinned: {response.data.pinned}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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 });

  // Unpin a List
  const response = await client.lists.unpin("2244994945", "1454155907651158017");

  console.log(`Pinned: ${response.data?.pinned}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "pinned": false
  }
}
```

***

## Important notes

<Note>
  * You can only pin Lists you follow or own
  * Pinned Lists appear at the top of your Lists in the X app
  * There's a limit on how many Lists you can pin
</Note>

***

## Next steps

<CardGroup>
  <Card title="Pinned Lists lookup" icon="thumbtack" href="/x-api/lists/pinned-lists/quickstart/pinned-list-lookup">
    Get your pinned Lists
  </Card>

  <Card title="List lookup" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/lists/list-lookup/quickstart">
    Get List details
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/lists/pin-list">
    Full endpoint documentation
  </Card>
</CardGroup>


# Pinned Lists Overview
Source: https://docs.x.com/x-api/lists/pinned-lists/quickstart/overview

The pinned Lists endpoints let you look up a user's pinned Lists and manage which Lists are. Reference for the X API v2 standard tier covering quickstart.

The pinned Lists endpoints let you look up a user's pinned Lists and manage which Lists are pinned.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Available endpoints

<CardGroup>
  <Card title="Pinned Lists lookup" icon="thumbtack" href="/x-api/lists/pinned-lists/quickstart/pinned-list-lookup">
    Get your pinned Lists
  </Card>

  <Card title="Manage pinned Lists" icon="pin" href="/x-api/lists/pinned-lists/quickstart/manage-pinned-lists">
    Pin and unpin Lists
  </Card>
</CardGroup>

***

## Authentication

| Operation            | Authentication               |
| :------------------- | :--------------------------- |
| Look up pinned Lists | OAuth 1.0a or OAuth 2.0 PKCE |
| Pin/unpin Lists      | OAuth 1.0a or OAuth 2.0 PKCE |

<Warning>
  Both lookup and manage operations require user context authentication. App-only (Bearer Token) authentication is not supported.
</Warning>

***

## Quick example

<CodeGroup>
  ```bash cURL theme={null}
  # Get pinned Lists
  curl "https://api.x.com/2/users/2244994945/pinned_lists" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get pinned Lists
  response = client.lists.get_pinned("2244994945")

  for lst in response.data:
      print(f"{lst.name}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get pinned Lists
  const response = await client.lists.getPinned("2244994945");

  response.data?.forEach((lst) => {
    console.log(lst.name);
  });
  ```
</CodeGroup>

***

## Next steps

<CardGroup>
  <Card title="List lookup" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/lists/list-lookup/quickstart">
    Get List details
  </Card>

  <Card title="Manage Lists" icon="pen" href="/x-api/lists/manage-lists/quickstart">
    Create and update Lists
  </Card>
</CardGroup>


# Pinned Lists Lookup
Source: https://docs.x.com/x-api/lists/pinned-lists/quickstart/pinned-list-lookup

Quickstart for retrieving a user's pinned X Lists using the X API v2 pinned Lists lookup endpoint, including authentication and sample responses.

This guide walks you through retrieving a user's pinned Lists.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Get pinned Lists

<Steps>
  <Step title="Get your user ID">
    You need your authenticated user's ID. You can find it using the [user lookup endpoint](/x-api/users/lookup/introduction) or from your Access Token (the numeric part is your user ID).
  </Step>

  <Step title="Request pinned Lists">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/users/2244994945/pinned_lists?\
      list.fields=follower_count,member_count,owner_id&\
      expansions=owner_id&\
      user.fields=created_at,username" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

      # Get pinned Lists
      response = client.lists.get_pinned(
          "2244994945",
          list_fields=["follower_count", "member_count", "owner_id"],
          expansions=["owner_id"],
          user_fields=["created_at", "username"]
      )

      for lst in response.data:
          print(f"{lst.name} - {lst.follower_count} followers")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

      // Get pinned Lists
      const response = await client.lists.getPinned("2244994945", {
        listFields: ["follower_count", "member_count", "owner_id"],
        expansions: ["owner_id"],
        userFields: ["created_at", "username"],
      });

      response.data?.forEach((lst) => {
        console.log(`${lst.name} - ${lst.follower_count} followers`);
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": [
        {
          "id": "1454155907651158017",
          "name": "Tech News",
          "follower_count": 150,
          "member_count": 25,
          "owner_id": "2244994945"
        }
      ],
      "includes": {
        "users": [
          {
            "id": "2244994945",
            "username": "XDevelopers",
            "name": "X Developers",
            "created_at": "2013-12-14T04:35:55.000Z"
          }
        ]
      },
      "meta": {
        "result_count": 1
      }
    }
    ```
  </Step>
</Steps>

***

## Available List fields

| Field            | Description             |
| :--------------- | :---------------------- |
| `description`    | List description        |
| `owner_id`       | Owner's user ID         |
| `private`        | Whether List is private |
| `member_count`   | Number of members       |
| `follower_count` | Number of followers     |
| `created_at`     | List creation date      |

***

## Next steps

<CardGroup>
  <Card title="Manage pinned Lists" icon="thumbtack" href="/x-api/lists/pinned-lists/quickstart/manage-pinned-lists">
    Pin and unpin Lists
  </Card>

  <Card title="List lookup" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/lists/list-lookup/quickstart">
    Get List details
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-pinned-lists">
    Full endpoint documentation
  </Card>
</CardGroup>


# Remove a List member
Source: https://docs.x.com/x-api/lists/remove-a-list-member

delete /2/lists/{id}/members/{user_id}
Removes a User from a List by their ID.



# Remove a List member
Source: https://docs.x.com/x-api/lists/remove-list-member

delete /2/lists/{id}/members/{user_id}
Removes a User from a List by their ID.



# Update List
Source: https://docs.x.com/x-api/lists/update-list

put /2/lists/{id}
Updates the details of a specific List owned by the authenticated user by its ID.



# Check Marketplace handle availability
Source: https://docs.x.com/x-api/marketplace/get-marketplace-handle-availability

get /2/marketplace/handles/{handle}/availability
Check whether a specific X handle is available to purchase through the Marketplace handle availability endpoint of the X API v2, with example responses.



# Append Media Upload
Source: https://docs.x.com/x-api/media/append-media-upload

post /2/media/upload/{id}/append



# Create Media metadata
Source: https://docs.x.com/x-api/media/create-media-metadata

post /2/media/metadata
Creates metadata for a Media file.



# Create Media subtitles
Source: https://docs.x.com/x-api/media/create-media-subtitles

post /2/media/subtitles
Creates subtitles for a specific Media file.



# Delete Media subtitles
Source: https://docs.x.com/x-api/media/delete-media-subtitles

delete /2/media/subtitles
Deletes subtitles for a specific Media file.



# Finalize Media upload
Source: https://docs.x.com/x-api/media/finalize-media-upload

post /2/media/upload/{id}/finalize
Finalizes a Media upload request.



# Get Media analytics
Source: https://docs.x.com/x-api/media/get-media-analytics

get /2/media/analytics



# Get Media by media key
Source: https://docs.x.com/x-api/media/get-media-by-media-key

get /2/media/{media_key}



# Get Media by media keys
Source: https://docs.x.com/x-api/media/get-media-by-media-keys

get /2/media



# Get Media upload status
Source: https://docs.x.com/x-api/media/get-media-upload-status

get /2/media/upload
Retrieves the status of a Media upload by its ID.



# Initialize media upload
Source: https://docs.x.com/x-api/media/initialize-media-upload

post /2/media/upload/initialize
Initializes a media upload.



# Media upload endpoints on the X API v2
Source: https://docs.x.com/x-api/media/introduction

Upload images, GIFs, and videos to X with chunked or simple media upload, retrieve media_id values, and attach them to Posts, Direct Messages, and profiles.

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.

## Media types & size restrictions

Size restrictions for uploading via API

* **Image**: `5 MB`
* **GIF**: `15 MB`
* **Video**: `512 MB` (when using `media_category=amplify_video`)

## Creation

Objects such as Posts, Direct Messages, user profile pictures, hosted Ads cards, etc. can contain one or more media objects. These top-level objects are collectively known as entities. The relevant entity creation API (e.g. [`POST /2/tweets`](/x-api/posts/creation-of-a-post)) can be passed one or more media objects using a unique `media_id`.

An entity which contains media object(s) can be created by following these steps:

1. Upload the media file(s) using either the recommended [chunked](/x-api/media/quickstart/media-upload-chunked) upload (images/GIF/video), or the older [simple](/x-api/media/upload-media) upload (images only).
2. Receive a `media_id` from step 1. This step may be repeated multiple times with different media if the entity allows multiple `media_id` parameters to be passed in.
3. Create the entity by calling the appropriate endpoint, including the `media_id` and other required parameters. For example, attach a `media_id` to a Post using the [`POST /2/tweets`](/x-api/posts/creation-of-a-post) endpoint.

## Retrieving

Please refer to the [Media Object](/x-api/fundamentals/data-dictionary/reference#media) in the data dictionary.


# Best practices
Source: https://docs.x.com/x-api/media/quickstart/best-practices

Important concepts and best practices for using the POST /2/media/upload endpoint. Reference for the X API v2 standard tier covering quickstart.

There are a few important concepts to understand when using the [`POST /2/media/upload`](/x-api/media/upload-media) 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.

## Keep in mind

* You may attach up to 4 photos, 1 animated GIF or 1 video in a Post.
* The image passed should be the raw binary of the image or binary base64 encoded, no need to otherwise encode or escape the contents as long as the Content-Type is set appropriately (when in doubt: `application/octet-stream`).
* When posting base64 encoded images, be sure to set the “Content-Transfer-Encoding: base64” on the image part of the message.
* Multi-part message boundaries must be on their own line and terminated by a CRLF.
* For working examples of how to POST using this endpoint, we recommend testing with [xurl](https://github.com/xdevplatform/xurl). Also, take a look at the [X Libraries](/resources/tools-and-libraries) available.
* Use the `media_id_string` provided in the API response for Javascript and any other languages that cannot accurately represent a long integer.

## Media categories

The Media Category parameter defines the use case of the media file to be uploaded, and can affect file size limits or other constraints enforced for media uploads. It’s important to use the correct media category when uploading media to avoid problems when trying to use the media. It is an optional value passed in the INIT request as part of the upload flow. If media category is not specified, the uploaded media is assumed to be media for a Post (`tweet_image`, `tweet_video`, or `tweet_gif`), depending on the content type.

The most common media categories are as follows:

* `tweet_image`
* `tweet_video`
* `tweet_gif`
* `dm_image`
* `dm_video`
* `dm_gif`
* `subtitles`

If you are an Ads API partner please refer to [these docs](/x-ads-api/creatives#promoted-video) for more information on recommended media category for promoted video.

## Image specifications and recommendations

Image files must meet all of the following criteria:

* **Supported image media types**: `JPG`, `PNG`, `GIF`, `WEBP`
* **Image size**: `<= 5 MB`
* **Animated GIF size**: `<= 15 MB`

The file size limit above is enforced by the media upload endpoint. In addition, there is a separate product entity specific file size limit which is applied when calling the Post creation (or similar) endpoints with `media_id`. The file size limit and other constraints may vary depending on the `media_category` parameter.

## Animated GIF recommendations

A GIF may fail during Post creation even if it is within the file size limit. Adhere to the following constraints to improve success rates.

* **Resolution**: `<= 1280x1080` (`width` x `height`)
* **Number of frames**: `<= 350`
* **Number of pixels**: `<= 300 million` (`width` \* `height` \* `num_frames`)
* **File size**: `<= 15Mb`

In order to process larger GIFs, use the [chunked upload](/x-api/media/quickstart/media-upload-chunked) endpoint with the `media_category` parameter. This allows the server to process the GIF file asynchronously, which is a requirement for processing larger files. Pass `media_category=tweet_gif` to enable async upload behavior for Posts with an animated GIF.

## Video specifications and recommendations

Please use the Async Path for media uploads.

### Recommended

* **Video Codec**: `H264 High Profile`
* **Frame Rates**: `30 FPS`, `60 FPS`
* **Video Resolution**: `1280x720` (landscape), `720x1280` (portrait), `720x720` (square). Subscribed users can upload a 1080p video and get 1080p playback. Unsubscribed users can upload a 720p video and get a 720p playback.
* **Minimum Video Bitrate**: `5,000 kbps`
* **Minimum Audio Bitrate**: `128 kbps`
* **Audio Codec**: `AAC LC`
* **Aspect Ratio**: `16:9` (landscape or portrait), `1:1` (square)

### Advanced

* **Frame rate**: must be `60 FPS` or less
* **Dimensions**: must be between `32x32` and `1280x1024`
* **File size**: must not exceed `512 mb`
* **Duration**: must be between `0.5 seconds` and `140 seconds`
* **Aspect ratio**: must be between `1:3` and `3:1`
* **[Pixel aspect ratio](https://en.wikipedia.org/wiki/Pixel_aspect_ratio)**: must have `1:1`
* **Pixel format**: Only [YUV](https://en.wikipedia.org/wiki/YUV) 4:2:0 is supported
* Audio must be [`AAC` with Low Complexity profile](https://en.wikipedia.org/wiki/Advanced_Audio_Coding#Modular_encoding). (High-Efficiency `AAC` is not supported)
* Audio must be `mono` or `stereo`, not 5.1 or greater
* Must not have [`open GOP`](https://en.wikipedia.org/wiki/Group_of_pictures)
* Must use [`progressive scan`](https://en.wikipedia.org/wiki/Progressive_scan)

### Additional Information

In the table below each row represents an upload recommendation, but is not a requirement. All uploads are processed for optimization across multiple platforms.

| Orientation | Width | Height | Video Bitrate | Audio Bitrate |
| :---------- | :---- | :----- | :------------ | :------------ |
| Landscape   | 1280  | 720    | 2048K         | 128K          |
| Landscape   | 640   | 360    | 768K          | 64K           |
| Landscape   | 320   | 180    | 256K          | 64K           |
| Portrait    | 720   | 1280   | 2048K         | 128K          |
| Portrait    | 360   | 640    | 768K          | 64K           |
| Portrait    | 180   | 320    | 256K          | 64K           |
| Square      | 720   | 720    | 2048K         | 128K          |
| Square      | 480   | 480    | 768K          | 64K           |
| Square      | 240   | 240    | 256K          | 32K           |

For an example of how to upload media, please see the [chunked media upload documentation](/x-api/media/quickstart/media-upload-chunked).

### Troubleshooting

For issues with the Media APIs, browse the [Media API category](https://devcommunity.x.com/c/x-api/media-apis) in the developer forums for an answer.


# Chunked Media Upload
Source: https://docs.x.com/x-api/media/quickstart/media-upload-chunked

This guide walks you through uploading videos and large media files using the chunked upload. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through uploading videos and large media files using the chunked upload workflow.

For video or large media uploads, you must:

1. **INIT** — Initialize the upload and get a `media_id`
2. **APPEND** — Upload each chunk of the file
3. **FINALIZE** — Complete the upload
4. **STATUS** — (If needed) Wait for processing to complete

<Note>
  See [this sample code](https://github.com/xdevplatform/large-video-upload-python) for a complete Python example.
</Note>

***

## Step 1: Initialize upload (INIT)

Start the upload session to get a `media_id`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.x.com/2/media/upload" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
    -H "Content-Type: multipart/form-data" \
    -F "command=INIT" \
    -F "media_type=video/mp4" \
    -F "total_bytes=1048576" \
    -F "media_category=amplify_video"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Initialize chunked upload
  response = client.media.init_upload(
      media_type="video/mp4",
      total_bytes=1048576,
      media_category="amplify_video"
  )

  media_id = response.data.id
  print(f"Media ID: {media_id}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Initialize chunked upload
  const response = await client.media.initUpload({
    mediaType: "video/mp4",
    totalBytes: 1048576,
    mediaCategory: "amplify_video",
  });

  const mediaId = response.data?.id;
  console.log(`Media ID: ${mediaId}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "id": "1880028106020515840",
    "media_key": "13_1880028106020515840",
    "expires_after_secs": 1295999
  }
}
```

***

## Step 2: Upload chunks (APPEND)

Upload each chunk of the file. For example, split a 3 MB file into 3 chunks:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.x.com/2/media/upload" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
    -H "Content-Type: multipart/form-data" \
    -F "command=APPEND" \
    -F "media_id=1880028106020515840" \
    -F "segment_index=0" \
    -F "media=@/path/to/chunk1.mp4"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Upload chunks
  chunk_size = 1024 * 1024  # 1 MB chunks

  with open("video.mp4", "rb") as f:
      segment_index = 0
      while True:
          chunk = f.read(chunk_size)
          if not chunk:
              break
          
          client.media.append_upload(
              media_id=media_id,
              segment_index=segment_index,
              media=chunk
          )
          segment_index += 1
          print(f"Uploaded chunk {segment_index}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";
  import fs from "fs";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Upload chunks
  const chunkSize = 1024 * 1024; // 1 MB chunks
  const fileBuffer = fs.readFileSync("video.mp4");

  let segmentIndex = 0;
  for (let offset = 0; offset < fileBuffer.length; offset += chunkSize) {
    const chunk = fileBuffer.slice(offset, offset + chunkSize);
    
    await client.media.appendUpload({
      mediaId,
      segmentIndex,
      media: chunk,
    });
    
    console.log(`Uploaded chunk ${segmentIndex + 1}`);
    segmentIndex++;
  }
  ```
</CodeGroup>

<Info>
  **Chunking advantages:**

  * Improved reliability on slow networks
  * Uploads can be paused and resumed
  * Failed chunks can be retried individually
</Info>

***

## Step 3: Finalize upload (FINALIZE)

Complete the upload after all chunks are sent:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.x.com/2/media/upload" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
    -H "Content-Type: multipart/form-data" \
    -F "command=FINALIZE" \
    -F "media_id=1880028106020515840"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Finalize upload
  response = client.media.finalize_upload(media_id=media_id)

  print(f"Processing state: {response.data.processing_info.state}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Finalize upload
  const response = await client.media.finalizeUpload({ mediaId });

  console.log(`Processing state: ${response.data?.processing_info?.state}`);
  ```
</CodeGroup>

**Response:**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "id": "1880028106020515840",
    "media_key": "13_1880028106020515840",
    "size": 1048576,
    "expires_after_secs": 86400,
    "processing_info": {
      "state": "pending",
      "check_after_secs": 1
    }
  }
}
```

<Note>
  If `processing_info` is returned, proceed to Step 4 to wait for processing. If not, the media is ready to use.
</Note>

***

## Step 4: Check status (STATUS)

If `processing_info` was returned, poll for processing completion:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/media/upload?command=STATUS&media_id=1880028106020515840" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client
  import time

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Wait for processing to complete
  while True:
      response = client.media.get_status(media_id=media_id)
      state = response.data.processing_info.state
      
      if state == "succeeded":
          print("Media ready!")
          break
      elif state == "failed":
          print("Processing failed")
          break
      else:
          check_after = response.data.processing_info.check_after_secs
          print(f"Processing... checking again in {check_after}s")
          time.sleep(check_after)
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Wait for processing to complete
  while (true) {
    const response = await client.media.getStatus({ mediaId });
    const state = response.data?.processing_info?.state;
    
    if (state === "succeeded") {
      console.log("Media ready!");
      break;
    } else if (state === "failed") {
      console.log("Processing failed");
      break;
    } else {
      const checkAfter = response.data?.processing_info?.check_after_secs ?? 1;
      console.log(`Processing... checking again in ${checkAfter}s`);
      await new Promise((r) => setTimeout(r, checkAfter * 1000));
    }
  }
  ```
</CodeGroup>

**Processing states:** `pending` → `in_progress` → `succeeded` or `failed`

***

## Step 5: Create Post with media

Once processing is complete, create a Post with the media:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.x.com/2/tweets" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Check out this video!",
      "media": {
        "media_ids": ["1880028106020515840"]
      }
    }'
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Create Post with media
  response = client.posts.create(
      text="Check out this video!",
      media={"media_ids": [media_id]}
  )

  print(f"Posted: {response.data.id}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Create Post with media
  const response = await client.posts.create({
    text: "Check out this video!",
    media: { mediaIds: [mediaId] },
  });

  console.log(`Posted: ${response.data?.id}`);
  ```
</CodeGroup>

***

## Media categories

| Category        | Description             |
| :-------------- | :---------------------- |
| `tweet_image`   | Image for a Post        |
| `tweet_gif`     | Animated GIF for a Post |
| `tweet_video`   | Video for a Post        |
| `amplify_video` | Amplify video           |

***

## Next steps

<CardGroup>
  <Card title="Best practices" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/media/quickstart/best-practices">
    File constraints and requirements
  </Card>

  <Card title="Create Posts" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f" href="/x-api/posts/manage-tweets/quickstart">
    Post with media
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/media/initialize-media-upload">
    Full endpoint documentation
  </Card>
</CardGroup>


# Upload media
Source: https://docs.x.com/x-api/media/upload-media

post /2/media/upload
Uploads a media file for use in posts or other content.



# Data Formation Migration
Source: https://docs.x.com/x-api/migrate/data-format-migration

Map fields from v1.1 Native, enterprise Native Enriched, and Activity Streams payloads to the X API v2 data format using fields and expansions.

## 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, premi


# Overview
Source: https://docs.x.com/x-api/migrate/overview

The latest version of the X API v2 is a big deal. As such, we’ve broken this migration section into a few partitions: The X API v2 is now the primary X API.

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:

<Button href="/x-api/migrate/x-api-endpoint-map">
  X API Endpoint Map
</Button>

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/reference#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/fundamentals/recovery-and-redundancy)
* [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/reference#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/reference#user)    | The user object contains X user account metadata describing the referenced user.                                                                                                                                 |
| [Spaces](/x-api/fundamentals/data-dictionary/reference#space) | The Space object consists of fields such                                                                                                                                                                         |


# Ready to migrate
Source: https://docs.x.com/x-api/migrate/ready-to-migrate





# X API endpoint map: v1.1 and Enterprise to v2
Source: https://docs.x.com/x-api/migrate/x-api-endpoint-map

Comprehensive map of Standard v1.1 and Enterprise endpoints alongside their X API v2 equivalents to plan and execute your migration to v2.

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 <br />GET statuses/lookup                                                           |                                                                                                        | [Posts lookup](/x-api/posts/lookup/introduction)                                                                                                           |
|           | POST statuses/update <br /> POST statuses/destroy/:id                                                 |                                                                                                        | [Manage Posts](/x-api/posts/manage-tweets/introduction)                                                                                                    |
|           | GET statuses/user\_timeline <br /> GET statuses/mentions\_timeline <br /> GET statuses/home\_timeline |                                                                                                        | [Timelines](/x-api/posts/timelines/introduction)  <br />- User Post timeline  <br />- User mention timeline  <br />- Reverse chronological home timeline   |
|           | GET search/tweets                                                                                     | [Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api) <br />- 30 day  <br />- Full-archive  | [Search Tweets](/x-api/posts/search/introduction)  <br />- Recent search  <br />- 30 day \[No Replacement Planned]  <br />- Full-archive search            |
|           |                                                                                                       | [Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api)  <br />- 30 day  <br />- Full-archive | [Tweet counts](/x-api/posts/counts/introduction)  <br />- Recent Tweet counts  <br />- 30 day \[No Replacement Planned]  <br />- 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)  <br />- Connect to stream  <br />- Add/delete rules  <br />- Retrieve rules                  |
|           | GET statuses/sample (1%)                                                                              | [Decahose API](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api)  <br />Firehose API               | [Volume stream](/x-api/posts/volume-streams/introduction)  <br />- 1% sampled stream  <br />- 10% decahose stream   <br />- 100% firehose stream           |
|           | GET statuses/retweeters/:ids  <br />GET statuses/retweets/:id                                         |                                                                                                        | [Retweets lookup](/x-api/posts/retweets/introduction)                                                                                                      |
|           |                                                                                                       |                                                                                                        | [Quote Tweets lookup](/x-api/posts/quote-tweets)                                                                                                           |
|           | POST statuses/retweet/:id  <br />POST statuses/unretweet/:id                                          |                                                                                                        | [Manage Retweets](/x-api/posts/retweets/introduction)  <br />- Retweet a Tweet  <br />- Undo a Retweet                                                     |
|           | GET favorites/list                                                                                    |                                                                                                        | [Likes lookup](/x-api/posts/likes/introduction)  <br />- Posts liked by a user  <br />- Users who have liked a Post                                        |
|           | POST favorites/create  <br />POST favorites/destroy                                                   |                                                                                                        | [Manage Likes](/x-api/posts/likes/introduction)  <br />- Like a Post  <br />- Unlike a Post                                                                |
|           |                                                                                                       |                                                                                                        | [Hide replies](/x-api/posts/hide-replies/introduction)                                                                                                     |


# Get news stories by ID
Source: https://docs.x.com/x-api/news/get-news-stories-by-id

get /2/news/{id}
Retrieves news story by its ID.



# News lookup endpoint on the X API v2
Source: https://docs.x.com/x-api/news/introduction

Look up breaking news stories and headlines on X with the v2 news endpoint, including summaries, hooks, contexts, tickers, and clustered Post results.

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 and OAuth2 PKCE.

## Getting started

To use the endpoint, you need a [bearer token](/fundamentals/authentication/oauth-2-0/application-only) from the [Developer Console](https://developer.x.com/en/portal/dashboard).

Once you have the bearer token, you can call the news API as shown below:

```bash theme={null}
curl 'https://api.x.com/2/news/1989418137272422538?news.fields=contexts,cluster_posts_results' --header 'Authorization: Bearer XXXXX'
```

If the request is successful, you should see the JSON response as shown below:

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data":{
    "category":"News",
    "name":"Nebius Group Stock Plunges 30% Despite Q3 Revenue Surge and Meta Deal",
    "summary":"Nebius Group announced third-quarter revenue of $214 million, a fourfold increase year-over-year, alongside a $3 billion five-year GPU cloud services contract with Meta Platforms on November 11, 2025. Despite these positives, shares fell over 30% to $83.58 by November 14, driven by AI sector cooling and a $119.6 million net loss. Analysts hold a strong Buy rating with an average price target of $139.67, while X users see the dip as a buying opportunity.",
    "hook":"Nebius Group's shares cratered 30% after blockbuster Q3 earnings and a $3 billion Meta deal—yet analysts and investors are calling it a golden buying chance amid AI hype.",
    "contexts":{
      "sports":{
        "teams":[]
      },
      "entities":{
        "events":[],
        "organizations":[
          "Goldman Sachs",
          "Nebius Group N.V."
        ],
        "people":[],
        "places":[],
        "products":[]
      },
      "topics":[
        "Stocks"
      ],
      "finance":{
        "tickers":[
          "NBIS"
        ]
      }
    },
    "cluster_posts_results":[
      {
        "post_id":"1989409257394245835"
      },
      {
        "post_id":"1989410019562197162"
      },
      {
        "post_id":"1989413132993999177"
      },
      {
        "post_id":"1989411147179610400"
      },
      {
        "post_id":"1989409829937656067"
      },
      {
        "post_id":"1989415596249985296"
      },
      {
        "post_id":"1989415537781477721"
      },
      {
        "post_id":"1989413002739691628"
      },
      {
        "post_id":"1989414454644363445"
      },
      {
        "post_id":"1989411489988710860"
      }
    ],
    "disclaimer":"This story is a summary of posts on X and may evolve over time. Grok can make mistakes, verify its outputs.",
    "last_updated_at_ms":"2025-11-17T16:21:41.000Z",
    "id":"1989418137272422538"
  }
}
```


# Search News
Source: https://docs.x.com/x-api/news/search-news

get /2/news/search



# X API Overview
Source: https://docs.x.com/x-api/overview

Complete X API v2 reference covering Posts, users, Spaces, Direct Messages, lists, trends, media, compliance, streaming, and webhook endpoints.

The X API gives you programmatic access to X's public conversation. All endpoints below are available on [pay-per-use](/x-api/introduction) plans. Endpoints marked as Enterprise-only require an [Enterprise](/enterprise-api/introduction) plan.

***

## Endpoints

<CardGroup>
  <Card title="Posts" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f" href="/x-api/posts/lookup/introduction">
    Search, retrieve, and publish posts. Access timelines, threads, and quote posts.
  </Card>

  <Card title="Users" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305" href="/x-api/users/lookup/introduction">
    Look up profiles, manage follows, blocks, and mutes.
  </Card>

  <Card title="Direct Messages" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-envelope.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=fbd38dbcd64d8688d3c9912ac30c4621" href="/x-api/direct-messages/lookup/introduction">
    Send and receive private messages.
  </Card>

  <Card title="Spaces" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-microphone.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=84616ff8f3d942047a71ee5e0a5adab9" href="/x-api/spaces/lookup/introduction">
    Find live audio conversations and participants.
  </Card>

  <Card title="Lists" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/lists/list-lookup/introduction">
    Create and manage curated lists of accounts.
  </Card>

  <Card title="Likes" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-heart.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=3a435e6393c019d681c6f1a0737e21a8" href="/x-api/posts/likes/introduction">
    Like and unlike posts. Look up who liked a post.
  </Card>

  <Card title="Trends" icon="https://mintcdn.com/x-preview/UIyI4eSwiP2OpODQ/icons/xds/icon-feather-chart-line.svg?fit=max&auto=format&n=UIyI4eSwiP2OpODQ&q=85&s=185e7e1271f798947403bb3f0c44f294" href="/x-api/trends/trends-by-woeid/introduction">
    Trending topics by location and personalized trends.
  </Card>

  <Card title="Media" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-photo.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=d0986097dcff55478c32801b20440ecc" href="/x-api/media/introduction">
    Upload images, videos, and GIFs. Manage subtitles and metadata.
  </Card>

  <Card title="Communities" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980" href="/x-api/communities/lookup/introduction">
    Look up and search communities.
  </Card>

  <Card title="Community Notes" icon="note-sticky" href="/x-api/community-notes/introduction">
    Create, evaluate, and search community notes.
  </Card>

  <Card title="News" icon="newspaper" href="/x-api/news/introduction">
    Search and retrieve news stories.
  </Card>

  <Card title="Compliance" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-check.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=768533bde161ac68862de87449f011c3" href="/x-api/compliance/batch-compliance/introduction">
    Batch compliance jobs and compliance streams.
  </Card>
</CardGroup>

***

## Streaming & real-time

<CardGroup>
  <Card title="Filtered Stream" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e" href="/x-api/posts/filtered-stream/introduction">
    Get posts delivered in real-time matching your filter rules.
  </Card>

  <Card title="X Activity" icon="bolt" href="/x-api/activity/introduction">
    Subscribe to real-time activity events like follows, likes, and profile updates.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/x-api/webhooks/introduction">
    Receive event data via HTTP callbacks.
  </Card>
</CardGroup>

***

## Enterprise-only

These endpoints require an [Enterprise plan](/enterprise-api/introduction).

<CardGroup>
  <Card title="Volume Streams" icon="satellite-dish" href="/x-api/posts/volume-streams/introduction">
    Full firehose and language-specific streams.
  </Card>

  <Card title="Likes Streams" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-heart.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=3a435e6393c019d681c6f1a0737e21a8" href="/x-api/stream/likes-streams-introduction">
    Stream all or sampled likes in real-time.
  </Card>

  <Card title="Powerstream" icon="bolt" href="/x-api/powerstream/introduction">
    High-performance filtered streaming with advanced operators.
  </Card>

  <Card title="Analytics" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143" href="/x-api/posts/get-post-analytics">
    Post and media engagement metrics at scale.
  </Card>

  <Card title="Account Activity" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bell.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=5e0b3dcfbb39ba3d4619931d7cd927d1" href="/x-api/account-activity/introduction">
    Real-time user event subscriptions.
  </Card>

  <Card title="Stream Webhooks" icon="webhook" href="/x-api/webhooks/stream/introduction">
    Filtered stream delivery via webhooks.
  </Card>
</CardGroup>

***

## Quick start

```bash theme={null}
curl "https://api.x.com/2/users/by/username/xdevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

<CardGroup>
  <Card title="Make your first request" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/getting-started/make-your-first-request">
    Get your credentials and call the API in minutes.
  </Card>

  <Card title="SDKs" icon="cube" href="/tools-and-libraries">
    Official Python and TypeScript libraries.
  </Card>
</CardGroup>


# Integration guide
Source: https://docs.x.com/x-api/posts/bookmarks/integrate

This page contains information on several tools and critical concepts that you should know as. Reference for the X API v2 standard tier covering bookmarks.

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


# Bookmarks
Source: https://docs.x.com/x-api/posts/bookmarks/introduction

The Bookmarks endpoints let you view, add, and remove bookmarked Posts for the authenticated. Reference for the X API v2 standard tier covering bookmarks.

The Bookmarks endpoints let you view, add, and remove bookmarked Posts for the authenticated user. Bookmarks are private and only visible to the user who created them.

## Overview

<CardGroup>
  <Card title="View bookmarks" icon="bookmark">
    Get all bookmarked Posts
  </Card>

  <Card title="Add bookmark" icon="plus">
    Bookmark a Post
  </Card>

  <Card title="Remove bookmark" icon="minus">
    Remove a bookmarked Post
  </Card>

  <Card title="Bookmark folders" icon="folder">
    Organize bookmarks into folders
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                                                               | Description           |
| :----- | :------------------------------------------------------------------------------------- | :-------------------- |
| GET    | [`/2/users/:id/bookmarks`](/x-api/users/get-bookmarks)                                 | Get user's bookmarks  |
| POST   | [`/2/users/:id/bookmarks`](/x-api/users/create-bookmark)                               | Bookmark a Post       |
| DELETE | [`/2/users/:id/bookmarks/:tweet_id`](/x-api/users/delete-bookmark)                     | Remove a bookmark     |
| GET    | [`/2/users/:id/bookmarks/folders`](/x-api/users/get-bookmark-folders)                  | Get bookmark folders  |
| GET    | [`/2/users/:id/bookmarks/folders/:folder_id`](/x-api/users/get-bookmarks-by-folder-id) | Get Posts in a folder |

***

## Example: Get bookmarks

```bash theme={null}
curl "https://api.x.com/2/users/123456789/bookmarks?\
tweet.fields=created_at,author_id,public_metrics" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
```

## Example: Add bookmark

```bash theme={null}
curl -X POST "https://api.x.com/2/users/123456789/bookmarks" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tweet_id": "1234567890"}'
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * User Access Tokens via [OAuth 2.0 PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) or [3-legged OAuth](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow)
</Note>

<CardGroup>
  <Card title="Lookup quickstart" icon="bookmark" href="/x-api/posts/bookmarks/quickstart/bookmarks-lookup">
    Get a user's bookmarks
  </Card>

  <Card title="Manage quickstart" icon="plus" href="/x-api/posts/bookmarks/quickstart/manage-bookmarks">
    Add and remove bookmarks
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/bookmarks/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-bookmarks">
    Full endpoint documentation
  </Card>
</CardGroup>


# Bookmarks Lookup
Source: https://docs.x.com/x-api/posts/bookmarks/quickstart/bookmarks-lookup

This guide walks you through retrieving your bookmarked Posts using the X API. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through retrieving your bookmarked Posts using the X API.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token with `bookmark.read` scope (OAuth 2.0 PKCE)
</Note>

***

## Get your bookmarks

<Steps>
  <Step title="Get your user ID">
    You need your authenticated user's ID. You can find it using the `/2/users/me` endpoint or from the [user lookup endpoint](/x-api/users/lookup/introduction).
  </Step>

  <Step title="Request your bookmarks">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/users/2244994945/bookmarks?\
      tweet.fields=created_at,public_metrics,author_id&\
      max_results=10" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

      # Get bookmarked Posts with pagination
      for page in client.bookmarks.get(
          "2244994945",
          tweet_fields=["created_at", "public_metrics", "author_id"],
          max_results=10
      ):
          for post in page.data:
              print(f"{post.text[:50]}... - Likes: {post.public_metrics.like_count}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

      // Get bookmarked Posts with pagination
      const paginator = client.bookmarks.get("2244994945", {
        tweetFields: ["created_at", "public_metrics", "author_id"],
        maxResults: 10,
      });

      for await (const page of paginator) {
        page.data?.forEach((post) => {
          console.log(`${post.text?.slice(0, 50)}... - Likes: ${post.public_metrics?.like_count}`);
        });
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": [
        {
          "id": "1501258597237342208",
          "text": "Have you built a project using the X API you'd like to share with the community? We'd love to hear from you!",
          "created_at": "2024-01-15T10:30:00.000Z",
          "author_id": "2244994945",
          "public_metrics": {
            "retweet_count": 15,
            "reply_count": 8,
            "like_count": 89,
            "quote_count": 3
          }
        },
        {
          "id": "1501258542258348032",
          "text": "This is just one way developer innovation helps make X a better place...",
          "created_at": "2024-01-15T09:15:00.000Z",
          "author_id": "2244994945",
          "public_metrics": {
            "retweet_count": 22,
            "reply_count": 5,
            "like_count": 156,
            "quote_count": 7
          }
        }
      ],
      "meta": {
        "result_count": 2,
        "next_token": "7140dibdnow9c7btw4539n0vybdnx19ylpayqf16fjt4l"
      }
    }
    ```
  </Step>
</Steps>

***

## Include author information

Use expansions to get data about Post authors:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/2244994945/bookmarks?\
  tweet.fields=created_at,author_id&\
  expansions=author_id&\
  user.fields=username,verified" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get bookmarks with author info
  for page in client.bookmarks.get(
      "2244994945",
      tweet_fields=["created_at", "author_id"],
      expansions=["author_id"],
      user_fields=["username", "verified"]
  ):
      for post in page.data:
          print(f"{post.text[:50]}...")
      # Author info is in page.includes.users
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get bookmarks with author info
  const paginator = client.bookmarks.get("2244994945", {
    tweetFields: ["created_at", "author_id"],
    expansions: ["author_id"],
    userFields: ["username", "verified"],
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(`${post.text?.slice(0, 50)}...`);
    });
    // Author info is in page.includes?.users
  }
  ```
</CodeGroup>

***

## Required scopes

When using OAuth 2.0 PKCE, your access token must have these scopes:

| Scope           | Description                     |
| :-------------- | :------------------------------ |
| `bookmark.read` | Read bookmarks                  |
| `tweet.read`    | Read Post data                  |
| `users.read`    | Read user data (for expansions) |

***

## Next steps

<CardGroup>
  <Card title="Manage bookmarks" icon="bookmark" href="/x-api/posts/bookmarks/quickstart/manage-bookmarks">
    Add and remove bookmarks
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-bookmarks">
    Full endpoint documentation
  </Card>
</CardGroup>


# Manage Bookmarks
Source: https://docs.x.com/x-api/posts/bookmarks/quickstart/manage-bookmarks

This guide walks you through adding and removing bookmarks using the X API. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through adding and removing bookmarks using the X API.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token with `bookmark.write` scope (OAuth 2.0 PKCE)
</Note>

***

## Add a bookmark

<Steps>
  <Step title="Get your user ID">
    You need your authenticated user's ID. You can find it using the `/2/users/me` endpoint or the [user lookup endpoint](/x-api/users/lookup/introduction).
  </Step>

  <Step title="Get the Post ID">
    Find the Post ID in the URL when viewing a Post:

    ```
    https://x.com/XDevelopers/status/1460323737035677698
                                    └── This is the Post ID
    ```
  </Step>

  <Step title="Add the bookmark">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/users/2244994945/bookmarks" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"tweet_id": "1460323737035677698"}'
      ```

      ```python Python SDK theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

      # Add a bookmark
      response = client.bookmarks.create(
          user_id="2244994945",
          tweet_id="1460323737035677698"
      )

      print(f"Bookmarked: {response.data.bookmarked}")
      ```

      ```javascript JavaScript SDK theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

      // Add a bookmark
      const response = await client.bookmarks.create("2244994945", {
        tweetId: "1460323737035677698",
      });

      console.log(`Bookmarked: ${response.data?.bookmarked}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": {
        "bookmarked": true
      }
    }
    ```
  </Step>
</Steps>

***

## Remove a bookmark

Delete a Post from your bookmarks:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.x.com/2/users/2244994945/bookmarks/1460323737035677698" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Remove a bookmark
  response = client.bookmarks.delete(
      user_id="2244994945",
      tweet_id="1460323737035677698"
  )

  print(f"Bookmarked: {response.data.bookmarked}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Remove a bookmark
  const response = await client.bookmarks.delete("2244994945", "1460323737035677698");

  console.log(`Bookmarked: ${response.data?.bookmarked}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "bookmarked": false
  }
}
```

***

## Required scopes

When using OAuth 2.0 PKCE, your access token must have these scopes:

| Scope            | Description              |
| :--------------- | :----------------------- |
| `bookmark.write` | Add and remove bookmarks |
| `tweet.read`     | Read Post data           |
| `users.read`     | Read user data           |

***

## Next steps

<CardGroup>
  <Card title="Bookmarks lookup" icon="bookmark" href="/x-api/posts/bookmarks/quickstart/bookmarks-lookup">
    Get your bookmarked Posts
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/create-bookmark">
    Full endpoint documentation
  </Card>
</CardGroup>


# Build a query
Source: https://docs.x.com/x-api/posts/counts/integrate/build-a-query

Your queries will be limited depending on which access level you are using. Reference for the X API v2 standard tier covering integrate.

#### 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)](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


# Overview
Source: https://docs.x.com/x-api/posts/counts/integrate/overview

This page covers tools and key concepts for integrating the Post counts endpoints. Reference for the X API v2 standard tier covering integrate.

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.


# Post Counts
Source: https://docs.x.com/x-api/posts/counts/introduction

The Post counts endpoints return the volume of Posts matching a query over time, without returning. Reference for the X API v2 standard tier covering counts.

The Post counts endpoints return the volume of Posts matching a query over time, without returning the Posts themselves. Use these endpoints to analyze trends, understand conversation size, and refine queries before searching.

## Overview

<CardGroup>
  <Card title="Volume analysis" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143">
    Build trendlines and visualizations showing Post volume over time
  </Card>

  <Card title="Query refinement" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e">
    Estimate result size before running full search queries
  </Card>

  <Card title="Event detection" icon="calendar">
    Identify when conversations peaked around events
  </Card>

  <Card title="Efficient research" icon="gauge-high">
    Understand conversation scale without retrieving all Posts
  </Card>
</CardGroup>

***

## Endpoints

| Endpoint                                                                | Description                       | Access                  |
| :---------------------------------------------------------------------- | :-------------------------------- | :---------------------- |
| GET [`/2/tweets/counts/recent`](/x-api/posts/get-count-of-recent-posts) | Count Posts from last 7 days      | All developers          |
| GET [`/2/tweets/counts/all`](/x-api/posts/get-count-of-all-posts)       | Count Posts from complete archive | Pay-per-use, Enterprise |

***

## Granularity options

Specify how counts are grouped using the `granularity` parameter:

| Granularity | Description               | Use case             |
| :---------- | :------------------------ | :------------------- |
| `minute`    | Counts per minute         | Real-time monitoring |
| `hour`      | Counts per hour (default) | Daily analysis       |
| `day`       | Counts per day            | Long-term trends     |

***

## Recent counts

Count Posts from the **last 7 days**. Available to all developers.

### Features

* Counts grouped by minute, hour, or day
* Same query operators as recent search
* 512-character query length

### Example response

```json theme={null}
{
  "data": [
    { "start": "2024-01-15T00:00:00.000Z", "end": "2024-01-15T01:00:00.000Z", "tweet_count": 1523 },
    { "start": "2024-01-15T01:00:00.000Z", "end": "2024-01-15T02:00:00.000Z", "tweet_count": 1247 },
    { "start": "2024-01-15T02:00:00.000Z", "end": "2024-01-15T03:00:00.000Z", "tweet_count": 892 }
  ],
  "meta": {
    "total_tweet_count": 3662
  }
}
```

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/counts/quickstart/recent-tweet-counts">
    Make your first recent counts request
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/get-count-of-recent-posts">
    Full endpoint documentation
  </Card>
</CardGroup>

***

## Full-archive counts

Count Posts from the **complete archive** back to 2006.

<Note>
  Full-archive counts are available to pay-per-use and Enterprise customers.
</Note>

### Features

* Count historical Posts from any time period
* All query operators available
* 1,024-character query length (4,096 for Enterprise)

### Pagination

Results paginate at 31 days per response:

* **Day granularity**: 31 days per page
* **Hour granularity**: 744 hours (31 days) per page
* **Minute granularity**: 44,640 minutes (31 days) per page

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/counts/quickstart/full-archive-tweet-counts">
    Make your first full-archive counts request
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/get-count-of-all-posts">
    Full endpoint documentation
  </Card>
</CardGroup>

***

## Query operators

Post counts use the same query syntax as search endpoints:

```
python lang:en -is:retweet
```

<Card title="Build a query" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/counts/integrate/build-a-query">
  Learn query syntax and operators
</Card>

***

## Important notes

<Note>
  **Counts vs search results**

  Counts may not exactly match search results. Search endpoints apply additional compliance filtering that counts endpoints do not perform.
</Note>

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [Bearer Token](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Recent counts quickstart" icon="clock" href="/x-api/posts/counts/quickstart/recent-tweet-counts">
    Count Posts from the last 7 days
  </Card>

  <Card title="Full-archive quickstart" icon="vault" href="/x-api/posts/counts/quickstart/full-archive-tweet-counts">
    Count historical Posts
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/counts/integrate/overview">
    Key concepts and best practices
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# v1 to v2 (Enterprise)
Source: https://docs.x.com/x-api/posts/counts/migrate/enterprise-to-twitter-api-v2

Granularity Pagination Timezone Endpoint URLs App and Project requirement Available time periods. Reference for the X API v2 standard tier covering migrate.

### 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
  \*


# Overview
Source: https://docs.x.com/x-api/posts/counts/migrate/overview

The v2 Post counts endpoint will eventually replace the enterprise Search API’s counts endpoint. Reference for the X API v2 standard tier covering migrate.

## 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://gnip-api.x.com)                                                                                                              | [https://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  <br />[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  <br />The per minute rate limit will vary by partner as specified in your contract. | 180 requests per 15 min per user  <br />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  <br />toDate                                                                                                                                        | start\_time  <br />end\_time                                                                       |
| Request parameters for navigating by Post ID                                                                                                                       |                                                                                                                                                               | since\_id  <br />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://gnip-api.x.com)                                                         | [https://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  <br />[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  <br />POST                                                                                          | GET                                                                                                |
| Default request rate limits                                                                                                                                                                                                                | The per minute rate limit will vary by partner as specified in your contract.  <br />20 requests per sec | 300 requests per 15 min per App  <br />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  <br />toDate                                                                                   | start\_time  <br />end\_time                                                                       |
| Request parameters for navigating by Post ID                                                                                                                                                                                               |                                                                                                          | since\_id  <br />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)


# Full-Archive Post Counts
Source: https://docs.x.com/x-api/posts/counts/quickstart/full-archive-tweet-counts

This guide walks you through getting historical Post counts back to March 2006. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through getting historical Post counts back to March 2006.

<Warning>
  Full-archive Post counts requires [Self-serve](/x-api/getting-started/about-x-api) or [Enterprise](/x-api/getting-started/about-x-api) access.
</Warning>

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with Self-serve or Enterprise access
  * Your App's Bearer Token
</Note>

***

## Get full-archive Post counts

<Steps>
  <Step title="Build a query">
    Use the same query syntax as full-archive search. For example, to count Posts from @XDevelopers:

    ```
    from:XDevelopers
    ```
  </Step>

  <Step title="Set a time range">
    Specify `start_time` and `end_time` to search specific historical periods:

    | Parameter    | Format   | Example                |
    | :----------- | :------- | :--------------------- |
    | `start_time` | ISO 8601 | `2020-01-01T00:00:00Z` |
    | `end_time`   | ISO 8601 | `2020-12-31T23:59:59Z` |
  </Step>

  <Step title="Make the request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/tweets/counts/all?\
      query=from%3AXDevelopers&\
      start_time=2020-01-01T00%3A00%3A00Z&\
      end_time=2020-12-31T23%3A59%3A59Z&\
      granularity=day" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Get full-archive Post counts
      response = client.posts.count_all(
          query="from:XDevelopers",
          start_time="2020-01-01T00:00:00Z",
          end_time="2020-12-31T23:59:59Z",
          granularity="day"
      )

      for bucket in response.data:
          print(f"{bucket.start}: {bucket.tweet_count} Posts")

      print(f"Total: {response.meta.total_tweet_count}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Get full-archive Post counts
      const response = await client.posts.countAll({
        query: "from:XDevelopers",
        startTime: "2020-01-01T00:00:00Z",
        endTime: "2020-12-31T23:59:59Z",
        granularity: "day",
      });

      response.data?.forEach((bucket) => {
        console.log(`${bucket.start}: ${bucket.tweet_count} Posts`);
      });

      console.log(`Total: ${response.meta?.total_tweet_count}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": [
        {
          "end": "2020-01-02T00:00:00.000Z",
          "start": "2020-01-01T00:00:00.000Z",
          "tweet_count": 3
        },
        {
          "end": "2020-01-03T00:00:00.000Z",
          "start": "2020-01-02T00:00:00.000Z",
          "tweet_count": 5
        }
      ],
      "meta": {
        "total_tweet_count": 8
      }
    }
    ```
  </Step>
</Steps>

***

## Granularity options

Control how counts are grouped:

| Granularity | Description               |
| :---------- | :------------------------ |
| `minute`    | Counts per minute         |
| `hour`      | Counts per hour (default) |
| `day`       | Counts per day            |

***

## Paginate through results

For large time ranges, use the `next_token` from the response:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/tweets/counts/all?\
  query=from%3AXDevelopers&\
  start_time=2015-01-01T00%3A00%3A00Z&\
  end_time=2020-12-31T23%3A59%3A59Z&\
  granularity=day&\
  next_token=abc123" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get counts with pagination
  next_token = None

  while True:
      response = client.posts.count_all(
          query="from:XDevelopers",
          start_time="2015-01-01T00:00:00Z",
          end_time="2020-12-31T23:59:59Z",
          granularity="day",
          next_token=next_token
      )
      
      for bucket in response.data:
          print(f"{bucket.start}: {bucket.tweet_count}")
      
      next_token = response.meta.next_token
      if not next_token:
          break
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get counts with pagination
  let nextToken = undefined;

  do {
    const response = await client.posts.countAll({
      query: "from:XDevelopers",
      startTime: "2015-01-01T00:00:00Z",
      endTime: "2020-12-31T23:59:59Z",
      granularity: "day",
      nextToken,
    });

    response.data?.forEach((bucket) => {
      console.log(`${bucket.start}: ${bucket.tweet_count}`);
    });

    nextToken = response.meta?.next_token;
  } while (nextToken);
  ```
</CodeGroup>

***

## Key differences from recent counts

| Feature            | Recent Counts  | Full-Archive Counts     |
| :----------------- | :------------- | :---------------------- |
| Time range         | Last 7 days    | March 2006 to now       |
| Access required    | All developers | Pay-per-use, Enterprise |
| Default time range | Last 7 days    | Last 30 days            |

***

## Common parameters

| Parameter     | Description                 | Default     |
| :------------ | :-------------------------- | :---------- |
| `query`       | Search query (required)     | —           |
| `granularity` | Time bucket size            | `hour`      |
| `start_time`  | Oldest timestamp (ISO 8601) | 30 days ago |
| `end_time`    | Newest timestamp (ISO 8601) | Now         |
| `next_token`  | Pagination token            | —           |

***

## Next steps

<CardGroup>
  <Card title="Recent counts" icon="clock" href="/x-api/posts/counts/quickstart/recent-tweet-counts">
    Get recent Post counts
  </Card>

  <Card title="Build a query" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/counts/integrate/build-a-query">
    Master query syntax
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/get-count-of-all-posts">
    Full endpoint documentation
  </Card>
</CardGroup>


# Recent Post Counts
Source: https://docs.x.com/x-api/posts/counts/quickstart/recent-tweet-counts

This guide walks you through getting Post counts (volume) for the last 7 days. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through getting Post counts (volume) for the last 7 days.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token
</Note>

***

## Get recent Post counts

<Steps>
  <Step title="Build a query">
    Use the same query syntax as recent search. For example, to count Posts from @XDevelopers:

    ```
    from:XDevelopers
    ```
  </Step>

  <Step title="Make the request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/tweets/counts/recent?\
      query=from%3AXDevelopers&\
      granularity=day" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Get recent Post counts
      response = client.posts.count_recent(
          query="from:XDevelopers",
          granularity="day"
      )

      for bucket in response.data:
          print(f"{bucket.start}: {bucket.tweet_count} Posts")

      print(f"Total: {response.meta.total_tweet_count}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Get recent Post counts
      const response = await client.posts.countRecent({
        query: "from:XDevelopers",
        granularity: "day",
      });

      response.data?.forEach((bucket) => {
        console.log(`${bucket.start}: ${bucket.tweet_count} Posts`);
      });

      console.log(`Total: ${response.meta?.total_tweet_count}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": [
        {
          "end": "2024-01-16T00:00:00.000Z",
          "start": "2024-01-15T00:00:00.000Z",
          "tweet_count": 5
        },
        {
          "end": "2024-01-17T00:00:00.000Z",
          "start": "2024-01-16T00:00:00.000Z",
          "tweet_count": 3
        },
        {
          "end": "2024-01-18T00:00:00.000Z",
          "start": "2024-01-17T00:00:00.000Z",
          "tweet_count": 8
        }
      ],
      "meta": {
        "total_tweet_count": 16
      }
    }
    ```
  </Step>
</Steps>

***

## Granularity options

Control how counts are grouped:

| Granularity | Description               |
| :---------- | :------------------------ |
| `minute`    | Counts per minute         |
| `hour`      | Counts per hour (default) |
| `day`       | Counts per day            |

<CodeGroup>
  ```bash cURL theme={null}
  # Get hourly counts
  curl "https://api.x.com/2/tweets/counts/recent?\
  query=python%20lang%3Aen&\
  granularity=hour" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get hourly counts
  response = client.posts.count_recent(
      query="python lang:en",
      granularity="hour"
  )

  for bucket in response.data:
      print(f"{bucket.start}: {bucket.tweet_count}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get hourly counts
  const response = await client.posts.countRecent({
    query: "python lang:en",
    granularity: "hour",
  });

  response.data?.forEach((bucket) => {
    console.log(`${bucket.start}: ${bucket.tweet_count}`);
  });
  ```
</CodeGroup>

***

## Filter by time range

Limit counts to a specific time period:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/tweets/counts/recent?\
  query=from%3AXDevelopers&\
  start_time=2024-01-10T00%3A00%3A00Z&\
  end_time=2024-01-15T00%3A00%3A00Z&\
  granularity=day" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get counts for a specific time range
  response = client.posts.count_recent(
      query="from:XDevelopers",
      start_time="2024-01-10T00:00:00Z",
      end_time="2024-01-15T00:00:00Z",
      granularity="day"
  )

  print(f"Total Posts: {response.meta.total_tweet_count}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get counts for a specific time range
  const response = await client.posts.countRecent({
    query: "from:XDevelopers",
    startTime: "2024-01-10T00:00:00Z",
    endTime: "2024-01-15T00:00:00Z",
    granularity: "day",
  });

  console.log(`Total Posts: ${response.meta?.total_tweet_count}`);
  ```
</CodeGroup>

***

## Common parameters

| Parameter     | Description                 | Default    |
| :------------ | :-------------------------- | :--------- |
| `query`       | Search query (required)     | —          |
| `granularity` | Time bucket size            | `hour`     |
| `start_time`  | Oldest timestamp (ISO 8601) | 7 days ago |
| `end_time`    | Newest timestamp (ISO 8601) | Now        |

***

## Next steps

<CardGroup>
  <Card title="Full-archive counts" icon="vault" href="/x-api/posts/counts/quickstart/full-archive-tweet-counts">
    Get historical Post counts
  </Card>

  <Card title="Build a query" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/counts/integrate/build-a-query">
    Master query syntax
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/get-count-of-recent-posts">
    Full endpoint documentation
  </Card>
</CardGroup>


# Create Posts
Source: https://docs.x.com/x-api/posts/create-or-edit-post

post /2/tweets



# Create Posts
Source: https://docs.x.com/x-api/posts/create-post

post /2/tweets

<Warning>
  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.
</Warning>


# Create Posts
Source: https://docs.x.com/x-api/posts/create-posts

post /2/tweets



# Delete Posts
Source: https://docs.x.com/x-api/posts/delete-post

delete /2/tweets/{id}



# Delete Posts
Source: https://docs.x.com/x-api/posts/delete-posts

delete /2/tweets/{id}



# Build a rule
Source: https://docs.x.com/x-api/posts/filtered-stream/integrate/build-a-rule

Build X API v2 Filtered Stream rules using keyword operators, conjunctions, and negations to deliver Posts that match your filter in near real time.

The filtered stream endpoints deliver Posts that match a set of rules applied to the stream. Rules are made up of operators that match on a variety of Post attributes.

Multiple rules can be applied using the [POST /tweets/search/stream/rules](/x-api/stream/update-stream-rules) endpoint. Once you've added rules and connected using [GET /tweets/search/stream](/x-api/stream/get-stream-rules), only Posts matching your rules will be delivered. You do not need to disconnect to add or remove rules.

***

## Rule limitations

Limits on the number of rules depend on your [access level](/x-api/getting-started/about-x-api). See the [filtered stream introduction](/x-api/posts/filtered-stream/introduction) for specific limits.

***

## 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, this rule works because `#hashtag` is a standalone operator:

```
#xapiv2
```

**Conjunction-required operators** cannot be used by themselves in a rule; they can only be used when at least one standalone operator is included. This is because using these operators alone would match an extremely high volume of Posts.

For example, the following rules are **not supported** since they contain only conjunction-required operators:

```
has:media
```

```
has:links OR is:retweet
```

```
embedding_threshold:0.45
```

If we add a standalone operator, such as the phrase `"X data"`, the rule works properly:

```
"X data" has:mentions (has:media OR has:links)
```

The `embedding_threshold:` operator (used with semantic `embedding:` rules) is also conjunction-required.

***

## Boolean operators and grouping

String together multiple operators using these tools:

| Operator                   | Description                           | Example                                                                 |
| :------------------------- | :------------------------------------ | :---------------------------------------------------------------------- |
| **AND** (space)            | Posts must match both conditions      | `snow day #NoSchool` matches Posts with "snow" AND "day" AND #NoSchool  |
| **OR**                     | Posts must match either condition     | `grumpy OR cat OR #meme` matches Posts with "grumpy" OR "cat" OR #meme  |
| **NOT** (dash)             | Exclude Posts matching this condition | `cat #meme -grumpy` matches Posts with "cat" and #meme but NOT "grumpy" |
| **Grouping** (parentheses) | Group operators together              | `(grumpy cat) OR (#meme has:images)` matches either group               |

<Note>
  **A note on negations**

  * All operators can be negated except for `sample:` and `embedding:`
  * The operator `-is:nullcast` must always be negated
  * Negated operators cannot be used alone
  * Do not negate grouped operators. Instead of `skiing -(snow OR day OR noschool)`, use `skiing -snow -day -noschool`
  * Writing `-embedding:"query"` is not supported
</Note>

***

## Order of operations

When combining AND and OR:

1. Operators connected by AND logic are combined first
2. Then, operators connected with OR logic are applied

**Examples:**

| Query                    | Evaluated as               |
| :----------------------- | :------------------------- |
| `apple OR iphone ipad`   | `apple OR (iphone ipad)`   |
| `ipad iphone OR android` | `(iphone ipad) OR android` |

To eliminate uncertainty, use parentheses:

```
(apple OR iphone) ipad
```

```
iphone (ipad OR android)
```

***

## Punctuation, diacritics, and case sensitivity

**Diacritics:** Filtered stream rules with accents only match Posts that also include the accent. For example, `diacrítica` matches *diacrítica* but **not** *diacritica*.

**Case sensitivity:** All operators are case-insensitive. The rule `cat` matches *cat*, *CAT*, and *Cat*.

<Note>
  **Search Posts behaves differently**

  When [building search queries](/x-api/posts/search/integrate/build-a-query), keywords with accents match Posts both with and without the accents. For example, `Diacrítica` matches both *Diacrítica* and *Diacritica*.
</Note>

***

## Quote Tweet matching

When using filtered stream, operators match on both the Quote Tweet's content **and** the content from the original Post that was quoted.

<Note>
  [Search Posts](/x-api/posts/search/introduction) behaves differently—it only matches on the Quote Tweet's content, not the original Post.
</Note>

***

## Specificity and efficiency

<Warning>
  Using broad operators like a single keyword or hashtag is not recommended—it will match a massive volume of Posts and quickly consume your connection.
</Warning>

**Tips for building effective rules:**

1. **Start specific, then broaden** — Create targeted rules that return relevant results
2. **Use multiple operators** — Combine operators to narrow results
3. **Watch your character count** — The entire rule string counts toward the limit

**Example progression:**

```
# Too broad - 200,000+ Posts per day
happy

# Better - adds language filter and exclusions
(happy OR happiness) lang:en -birthday -is:retweet

# Even better - 59 characters, more specific
(happy OR happiness) place_country:GB -birthday -is:retweet
```

***

## Iteratively building a rule

### Step 1: Start with a basic rule

```
happy OR happiness
```

### Step 2: Test and narrow based on results

We noticed Posts in many languages. Add a language filter:

```
(happy OR happiness) lang:en
```

We're getting birthday wishes. Exclude them and Retweets:

```
(happy OR happiness) lang:en -birthday -is:retweet
```

### Step 3: Broaden for better coverage

We want to capture more sentiment. Add related keywords:

```
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet
```

### Step 4: Adjust for trends

Holiday Posts are appearing. Exclude them:

```
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays
```

***

## Adding and removing rules

Use [POST /2/tweets/search/stream/rules](/x-api/stream/update-stream-rules) to add or remove rules.

### Adding rules

Submit an `add` JSON body with the `value` (the rule) and optional `tag` (to identify matching Posts):

```bash theme={null}
curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "add": [
      {"value": "cat has:media", "tag": "cats with media"},
      {"value": "cat has:media -grumpy", "tag": "happy cats with media"},
      {"value": "meme", "tag": "funny things"},
      {"value": "meme has:images"}
    ]
  }'
```

### Removing rules

Submit a `delete` JSON body with the rule IDs to remove:

```bash theme={null}
curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "delete": {
      "ids": [
        "1165037377523306498",
        "1165037377523306499"
      ]
    }
  }'
```

***

## Rule examples

### Tracking a natural disaster

Match Posts from weather agencies about Hurricane Harvey:

```json theme={null}
{
  "value": "-is:retweet 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)",
  "tag": "Hurricane Harvey - weather agencies with geo"
}
```

### Sentiment analysis for #nowplaying

**Positive sentiment:**

```json theme={null}
{
  "value": "#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",
  "tag": "#nowplaying positive"
}
```

**Negative sentiment:**

```json theme={null}
{
  "value": "#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",
  "tag": "#nowplaying negative"
}
```

### Using Post annotations

Find Japanese Posts about pets (not cats) with images using the `context:` operator:

First, use [Post lookup](/x-api/posts/lookup/introduction) with `tweet.fields=context_annotations` to identify domain.entity IDs:

* Cats: `domain` 66, `entity` 852262932607926273
* Pets: `domain` 65, `entity` 852262932607926273

```json theme={null}
{
  "value": "context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja",
  "tag": "Japanese pets with images - no cats"
}
```

### Semantic matching with embeddings (Enterprise)

Use the `embedding:` operator to match Posts by conceptual meaning rather than keywords. This requires Enterprise + Embedding tier.

```json theme={null}
{
  "value": "embedding:\"climate change policy\" embedding_threshold:0.4",
  "tag": "climate-semantic"
}
```

Combine with structural operators for precision:

```json theme={null}
{
  "value": "embedding:\"quarterly earnings surprises\" lang:en has:links -is:retweet",
  "tag": "earnings-en"
}
```

See the [operators reference](/x-api/posts/filtered-stream/integrate/operators) for full details and best practices.

***

## Next steps

<CardGroup>
  <Card title="Operators reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/posts/filtered-stream/integrate/operators">
    Complete list of available operators
  </Card>

  <Card title="Filtered stream quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/filtered-stream/quickstart">
    Connect to your stream
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code/tree/master/Filtered-Stream">
    Code examples in multiple languages
  </Card>
</CardGroup>


# Matching Posts to Rules
Source: https://docs.x.com/x-api/posts/filtered-stream/integrate/matching-returned-tweets

Use the matching_rules payload field to identify which X API v2 Filtered Stream rules a delivered Post matched, including tags and embedding scores.

### 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:**
 

```json theme={null}
"matching_rules": [
    {
      "id": "1166916266197536768",
      "tag": "test-rule-tag-00000"
    },
    {
      "id": "1166916266197536769",
      "tag": "test-rule-tag-12345"
    }
  ]
```

#### Embedding rule matches

When a Post matches a rule containing the `embedding:` operator, the `matching_rules` entry for that rule includes two additional fields (only present for embedding-based matches):

| Field                  | Description                                                                          |
| :--------------------- | :----------------------------------------------------------------------------------- |
| `embedding_similarity` | The cosine similarity score (0.0–1.0) between the rule's query and the matched Post. |
| `embedding_threshold`  | The threshold applied (your value or the default `0.3`).                             |

Example payload excerpt for an embedding match:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "id": "1784600000000000001",
    "text": "The new carbon tax proposal could reshape how industries approach emissions..."
  },
  "matching_rules": [
    {
      "id": "1784567890123456789",
      "tag": "climate-semantic",
      "embedding_similarity": 0.4523,
      "embedding_threshold": 0.4
    }
  ]
}
```

For keyword, `from:`, `has:`, and other non-embedding rules, `matching_rules` entries contain only `id` and `tag`.

#### 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>
  Note: These recovery and redundancy features are only available to those that have Enterprise access.
</Note>


# Filtered Stream Operators
Source: https://docs.x.com/x-api/posts/filtered-stream/integrate/operators

Complete X API v2 Filtered Stream operator reference, covering keyword, has:, is:, and Enterprise-only semantic embedding: operators for stream rules.

This page provides a complete list of operators available when [building rules](/x-api/posts/filtered-stream/integrate/build-a-rule) for Filtered Stream.

## Overview

Operators are used to match on specific Post attributes. There are two types:

* **Standalone operators** — Can be used alone or with any other operators
* **Conjunction-required operators** — Must be used with at least one standalone operator

Most operators are available on both Pay-per-use and Enterprise. Some advanced operators (such as semantic embedding) require Enterprise with additional tier access.

***

## Keyword and phrase operators

| Operator                | Type       | Summary                                                            | Example                               |
| :---------------------- | :--------- | :----------------------------------------------------------------- | :------------------------------------ |
| `keyword`               | Standalone | Matches a keyword within the Post body (tokenized match)           | `pepsi OR cola OR "coca cola"`        |
| `emoji`                 | Standalone | Matches an emoji within the Post body                              | `(😃 OR 😡) 😬`                       |
| `"exact phrase"`        | Standalone | Matches the exact phrase within the Post body                      | `("X API" OR #v2) -"filtered stream"` |
| `"keyword1 keyword2"~N` | Standalone | Proximity match — keywords within N tokens of each other (max N=6) | `"social media"~5`                    |

***

## Entity operators

| Operator | Type       | Summary                                          | Example                      |
| :------- | :--------- | :----------------------------------------------- | :--------------------------- |
| `#`      | Standalone | Matches Posts containing a hashtag (exact match) | `#thankunext #fanart`        |
| `@`      | Standalone | Matches Posts mentioning a username              | `(@XDevelopers OR @api) -@x` |
| `$`      | Standalone | Matches Posts containing a cashtag               | `$twtr OR @XDevelopers -$fb` |

***

## User operators

| Operator             | Type       | Summary                                                 | Example                         |
| :------------------- | :--------- | :------------------------------------------------------ | :------------------------------ |
| `from:`              | Standalone | Matches Posts from a specific user                      | `from:XDevelopers OR from:api`  |
| `to:`                | Standalone | Matches Posts in reply to a specific user               | `to:XDevelopers OR to:api`      |
| `retweets_of:`       | Standalone | Matches Retweets of a specific user                     | `retweets_of:XDevelopers`       |
| `from_affiliate_of:` | Standalone | Matches Posts from affiliates of a specific user        | `from_affiliate_of:XDevelopers` |
| `to_affiliate_of:`   | Standalone | Matches Posts in reply to affiliates of a specific user | `to_affiliate_of:XDevelopers`   |

***

## URL operators

| Operator           | Type       | Summary                                                         | Example                         |
| :----------------- | :--------- | :-------------------------------------------------------------- | :------------------------------ |
| `url:`             | Standalone | Tokenized match on URL (matches `url` or `expanded_url` fields) | `url:"https://developer.x.com"` |
| `url_title:`       | —          | Keyword match on expanded URL HTML title metadata               | `url_title:snow`                |
| `url_description:` | —          | Keyword match on expanded page description metadata             | `url_description:weather`       |
| `url_contains:`    | —          | Literal match on URL content                                    | `url_contains:photos`           |

***

## Context and entity operators

| Operator           | Type       | Summary                                           | Example                                           |
| :----------------- | :--------- | :------------------------------------------------ | :------------------------------------------------ |
| `context:`         | Standalone | Matches Posts with a specific domain/entity pair  | `context:10.799022225751871488` or `context:47.*` |
| `entity:`          | Standalone | Matches Posts with a specific entity string value | `entity:"Michael Jordan"`                         |
| `conversation_id:` | Standalone | Matches Posts in a conversation thread            | `conversation_id:1334987486343299072`             |

***

## User profile operators

| Operator        | Type       | Summary                                   | Example                                        |
| :-------------- | :--------- | :---------------------------------------- | :--------------------------------------------- |
| `bio:`          | Standalone | Matches keyword in Post author's bio      | `bio:developer OR bio:"data engineer"`         |
| `bio_name:`     | Standalone | Matches keyword in Post author's name     | `bio_name:phd OR bio_name:md`                  |
| `bio_location:` | Standalone | Matches keyword in Post author's location | `bio_location:"big apple" OR bio_location:nyc` |

***

## Location operators

| Operator         | Type       | Summary                                  | Example                                                     |
| :--------------- | :--------- | :--------------------------------------- | :---------------------------------------------------------- |
| `place:`         | Standalone | Matches Posts tagged with a location     | `place:"new york city" OR place:seattle`                    |
| `place_country:` | Standalone | Matches Posts with a country code        | `place_country:US OR place_country:MX`                      |
| `point_radius:`  | Standalone | Matches Posts within a radius of a point | `point_radius:[2.355128 48.861118 16km]`                    |
| `bounding_box:`  | Standalone | Matches Posts within a bounding box      | `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]` |

***

## Post type operators

| Operator       | Type                 | Summary                                      | Example                         |
| :------------- | :------------------- | :------------------------------------------- | :------------------------------ |
| `is:retweet`   | Conjunction required | Matches Retweets                             | `data @XDevelopers -is:retweet` |
| `is:reply`     | Conjunction required | Matches replies                              | `from:XDevelopers is:reply`     |
| `is:quote`     | Conjunction required | Matches Quote Tweets                         | `"sentiment analysis" is:quote` |
| `is:verified`  | Conjunction required | Matches Posts from verified authors          | `#nowplaying is:verified`       |
| `-is:nullcast` | Conjunction required | Excludes promotional Posts (must be negated) | `"mobile games" -is:nullcast`   |

***

## Content type operators

| Operator         | Type                 | Summary                                      | Example                              |
| :--------------- | :------------------- | :------------------------------------------- | :----------------------------------- |
| `has:hashtags`   | Conjunction required | Matches Posts with hashtags                  | `from:XDevelopers -has:hashtags`     |
| `has:cashtags`   | Conjunction required | Matches Posts with cashtags                  | `#stonks has:cashtags`               |
| `has:links`      | Conjunction required | Matches Posts with links                     | `from:XDevelopers has:links`         |
| `has:mentions`   | Conjunction required | Matches Posts with mentions                  | `#nowplaying has:mentions`           |
| `has:media`      | Conjunction required | Matches Posts with media (photo, GIF, video) | `(kittens OR puppies) has:media`     |
| `has:images`     | Conjunction required | Matches Posts with images                    | `#meme has:images`                   |
| `has:video_link` | Conjunction required | Matches Posts with native X videos           | `#icebucketchallenge has:video_link` |
| `has:geo`        | Conjunction required | Matches Posts with geolocation data          | `recommend #paris has:geo`           |

***

## Sampling and language operators

| Operator  | Type                 | Summary                                         | Example                          |
| :-------- | :------------------- | :---------------------------------------------- | :------------------------------- |
| `sample:` | Conjunction required | Returns a random percent sample (1-100)         | `#nowplaying @spotify sample:15` |
| `lang:`   | Conjunction required | Matches Posts classified as a specific language | `recommend #paris lang:en`       |

***

## User metrics operators

| Operator           | Type | Summary                                                                  | Example                       |
| :----------------- | :--- | :----------------------------------------------------------------------- | :---------------------------- |
| `min_followers:`   | —    | Matches Posts from users with at least the specified number of followers | `min_followers:1000`          |
| `followers_count:` | —    | Matches Posts from users with follower count in range                    | `followers_count:1000..10000` |
| `tweets_count:`    | —    | Matches Posts from users with Post count in range                        | `tweets_count:1000..10000`    |
| `following_count:` | —    | Matches Posts from users with following count in range                   | `following_count:1000..10000` |
| `listed_count:`    | —    | Matches Posts from users in specified number of Lists                    | `listed_count:10..100`        |

***

## Post reference operators

| Operator                | Type | Summary                                          | Example                                    |
| :---------------------- | :--- | :----------------------------------------------- | :----------------------------------------- |
| `in_reply_to_tweet_id:` | —    | Matches replies to a specific Post               | `in_reply_to_tweet_id:1539382664746020864` |
| `retweets_of_tweet_id:` | —    | Matches Retweets of a specific Post              | `retweets_of_tweet_id:1539382664746020864` |
| `source:`               | —    | Matches Posts from a specific source application | `source:"X for iPhone"`                    |

***

## Logical operators

| Operator    | Summary                          | Example                    |
| :---------- | :------------------------------- | :------------------------- |
| `OR`        | Logical OR between expressions   | `cat OR dog`               |
| Space (AND) | Logical AND between expressions  | `cat dog` (both required)  |
| `()`        | Grouping for complex expressions | `(cat OR dog) -is:retweet` |
| `-`         | Negation/exclusion               | `cat -grumpy`              |

***

## Embedding operators

<Note>
  **Enterprise only — Embedding tier required**

  The `embedding:` and `embedding_threshold:` operators are only available on Enterprise accounts provisioned with Embedding tier access for Filtered Stream. On unsupported tiers, rule creation will be rejected with an "unavailable operator" error. Contact your account representative to enable.
</Note>

These operators use a neural embedding model to match Posts by *semantic similarity* to a query, rather than requiring exact keyword matches.

| Operator                   | Type                 | Summary                                                                                         | Example                                                          |
| :------------------------- | :------------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| `embedding:"query"`        | Standalone           | Matches Posts semantically similar to the query. Multi-word queries must be quoted.             | `embedding:"climate change policy"`                              |
| `embedding_threshold:X.XX` | Conjunction required | Minimum cosine similarity for a match (0.0–1.0). Defaults to `0.3`. Use values between 0.3–0.6. | `embedding:"cryptocurrency regulation" embedding_threshold:0.45` |

### Key requirements and notes

* `embedding_threshold:` **cannot** be the only operator in a rule. Pair it with `embedding:` (or another standalone operator).
* **Do not negate** `embedding:` (e.g. `-embedding:"..."` is unsupported).
* Longer, descriptive natural language queries produce better results than short keywords.
* Embedding query processing is asynchronous — newly created rules may take a few seconds before they begin matching.
* When a Post matches via an embedding rule, the delivered payload's `matching_rules` entries will contain `embedding_similarity` and `embedding_threshold` (see [Matching Posts to Rules](/x-api/posts/filtered-stream/integrate/matching-returned-tweets)).

**Example rules:**

* `embedding:"electric vehicle announcements" lang:en -is:retweet has:links`
* `embedding:"natural disaster relief" embedding_threshold:0.45 has:media`
* `embedding:"renewable energy" embedding_threshold:0.4 OR embedding:"solar power investment"`

***

## Supported languages

The `lang:` operator supports these BCP 47 language codes:

| Language  | Code | Language   | Code | Language            | Code    |
| :-------- | :--- | :--------- | :--- | :------------------ | :------ |
| Amharic   | `am` | Greek      | `el` | Portuguese          | `pt`    |
| Arabic    | `ar` | Gujarati   | `gu` | Romanian            | `ro`    |
| Armenian  | `hy` | Hebrew     | `iw` | Russian             | `ru`    |
| Basque    | `eu` | Hindi      | `hi` | Serbian             | `sr`    |
| Bengali   | `bn` | Hungarian  | `hu` | Simplified Chinese  | `zh-CN` |
| Bulgarian | `bg` | Indonesian | `in` | Slovak              | `sk`    |
| Catalan   | `ca` | Italian    | `it` | Slovenian           | `sl`    |
| Croatian  | `hr` | Japanese   | `ja` | Spanish             | `es`    |
| Czech     | `cs` | Kannada    | `kn` | Swedish             | `sv`    |
| Danish    | `da` | Korean     | `ko` | Tamil               | `ta`    |
| Dutch     | `nl` | Latvian    | `lv` | Telugu              | `te`    |
| English   | `en` | Lithuanian | `lt` | Thai                | `th`    |
| Estonian  | `et` | Malayalam  | `ml` | Traditional Chinese | `zh-TW` |
| Finnish   | `fi` | Marathi    | `mr` | Turkish             | `tr`    |
| French    | `fr` | Norwegian  | `no` | Ukrainian           | `uk`    |
| German    | `de` | Persian    | `fa` | Urdu                | `ur`    |
| Georgian  | `ka` | Polish     | `pl` | Vietnamese          | `vi`    |

***

## Next steps

<CardGroup>
  <Card title="Build a rule" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e" href="/x-api/posts/filtered-stream/integrate/build-a-rule">
    Learn rule syntax and best practices
  </Card>

  <Card title="Filtered Stream introduction" icon="bolt" href="/x-api/posts/filtered-stream/introduction">
    Get started with Filtered Stream
  </Card>

  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Handle streaming disconnections
  </Card>
</CardGroup>


# Filtered Stream
Source: https://docs.x.com/x-api/posts/filtered-stream/introduction

Receive near real-time Posts that match custom rules with X API v2 Filtered Stream, using powerful operators to filter the public Post firehose.

The Filtered Stream endpoints let you receive near real-time Posts that match your filter rules. Create rules using powerful operators, then connect to a persistent stream to receive matching Posts as they're published.

<Note>
  Filtered Stream prioritizes data hydration and delivery, with approximately 6-7 seconds of P99 latency. For lower latency requirements, see [Powerstream](/x-api/powerstream/introduction).
</Note>

## Overview

<CardGroup>
  <Card title="Near real-time delivery" icon="bolt">
    Receive Posts within seconds of publication
  </Card>

  <Card title="Persistent rules" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e">
    Add and remove rules without disconnecting
  </Card>

  <Card title="Powerful operators" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834">
    Match on keywords, hashtags, users, and more
  </Card>

  <Card title="Webhook delivery" icon="webhook">
    Optionally receive Posts via webhooks
  </Card>
</CardGroup>

***

## How it works

1. **Create rules** — Define filter rules using operators
2. **Connect to stream** — Establish a persistent HTTP connection
3. **Receive Posts** — Get matching Posts in near real-time

```mermaid actions={false} theme={null}
flowchart LR
    A["Create/manage<br/>rules"] --> B["Connect to<br/>streaming endpoint"] --> C["Receive<br/>matching Posts"]
```

***

## Endpoints

| Method | Endpoint                                                             | Description           |
| :----- | :------------------------------------------------------------------- | :-------------------- |
| GET    | [`/2/tweets/search/stream`](/x-api/stream/stream-filtered-posts)     | Connect to the stream |
| POST   | [`/2/tweets/search/stream/rules`](/x-api/stream/update-stream-rules) | Add or delete rules   |
| GET    | [`/2/tweets/search/stream/rules`](/x-api/stream/get-stream-rules)    | List current rules    |

***

## Access levels

| Feature                      | Pay-per-use | Enterprise                  |
| :--------------------------- | :---------- | :-------------------------- |
| Rules per project            | 1,000       | 25,000+                     |
| Rule length                  | 1,024 chars | 2,048 chars                 |
| Connections                  | 1           | Multiple                    |
| Core operators               | ✓           | ✓                           |
| Semantic embedding operators | —           | ✓ (requires Embedding tier) |

<Card title="Contact for Enterprise" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bank.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=6dd9ad48fa88936abb112b49e022abff" href="https://developer.x.com/en/products/x-api/enterprise/enterprise-api-interest-form">
  Get higher limits and additional features
</Card>

<Note>
  Some operators require specific tiers. The `embedding:` semantic operator is available **only for Filtered Stream** on Enterprise plans with Embedding tier access. Standard Pay-per-use access includes core operators only.
</Note>

***

## Building rules

Rules use the same operators as search queries:

```
(AI OR "machine learning") lang:en -is:retweet
```

### Example rules

| Rule                                | Matches                                                               |
| :---------------------------------- | :-------------------------------------------------------------------- |
| `#python`                           | Posts with #python hashtag                                            |
| `from:elonmusk`                     | Posts by @elonmusk                                                    |
| `"breaking news" has:images`        | Posts with phrase and images                                          |
| `(@XDevelopers OR @X) -is:retweet`  | Mentions, excluding retweets                                          |
| `embedding:"climate change policy"` | Posts semantically about climate policy (Enterprise + Embedding tier) |

<Card title="Build a rule" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e" href="/x-api/posts/filtered-stream/integrate/build-a-rule">
  Learn rule syntax and operators
</Card>

***

## Connecting to the stream

Establish a persistent HTTP connection to receive Posts:

```python theme={null}
import requests

def stream_posts(bearer_token):
    url = "https://api.x.com/2/tweets/search/stream"
    headers = {"Authorization": f"Bearer {bearer_token}"}
    
    response = requests.get(url, headers=headers, stream=True)
    
    for line in response.iter_lines():
        if line:
            print(line.decode("utf-8"))
```

### Keep-alive signals

The stream sends blank lines (`\r\n`) every 20 seconds to maintain the connection. If you don't receive data or a keep-alive for 20 seconds, reconnect.

<CardGroup>
  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Reconnect gracefully
  </Card>

  <Card title="Consuming streaming data" icon="stream" href="/x-api/fundamentals/consuming-streaming-data">
    Process Posts efficiently
  </Card>
</CardGroup>

***

## Webhook delivery

Instead of maintaining a persistent connection, you can receive Posts via webhooks:

<Card title="Webhook delivery" icon="webhook" href="/x-api/webhooks/stream/introduction">
  Set up webhook delivery for filtered stream
</Card>

***

## Post edits

The stream delivers edited Posts with their edit history. Each edit creates a new Post ID:

```json theme={null}
{
  "data": {
    "id": "1234567893",
    "text": "Hello world! (edited)",
    "edit_history_tweet_ids": ["1234567890", "1234567891", "1234567893"]
  }
}
```

<Card title="Edit Posts fundamentals" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-history.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=6afe17587c08ee621e37afde19a07ff1" href="/x-api/fundamentals/edit-posts">
  Learn more about Post edits
</Card>

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [Bearer Token](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/filtered-stream/quickstart">
    Connect to the stream in minutes
  </Card>

  <Card title="Build a rule" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e" href="/x-api/posts/filtered-stream/integrate/build-a-rule">
    Learn rule syntax
  </Card>

  <Card title="Operator reference" icon="list-check" href="/x-api/posts/filtered-stream/integrate/operators">
    All available operators
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>

***

## Advanced topics

<CardGroup>
  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Reconnect gracefully
  </Card>

  <Card title="High volume capacity" icon="gauge-high" href="/x-api/fundamentals/high-volume-capacity">
    Handle high throughput
  </Card>

  <Card title="Recovery and redundancy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055" href="/x-api/fundamentals/recovery-and-redundancy">
    Build resilient applications
  </Card>

  <Card title="Matching returned Posts" icon="crosshairs" href="/x-api/posts/filtered-stream/integrate/matching-returned-tweets">
    Identify which rules matched
  </Card>
</CardGroup>


# Filtered stream migration overview
Source: https://docs.x.com/x-api/posts/filtered-stream/migrate/overview

Migrate filtered stream consumers from Standard v1.1 or PowerTrack to X API v2 by mapping endpoints, operators, rules, and authentication requirements.

## 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://stream.x.com)**                                                                                         | **[https://gnip-stream.x.com](https://gnip-stream.x.com)**                                                                                                                                                                      | **[https://api.x.com](https://api.x.com)**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Endpoint path                                                                   | **1.1/statuses/filter.json**                                                                                                             | **/stream/powertrack/accounts//publishers/twitter/.json**<br /><br />**/rules/powertrack/accounts//publishers/twitter/.json **<br /><br />**/rules/powertrack/accounts//publishers/twitter//validation.json**                   | **/2/tweets/search/stream**<br /><br />**/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  <br />POST                                                                                                                                                                                                                 | GET  <br />POST                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Required parameters                                                             | Rule defined on connection as parameter, at least one of:<br /><br />\* **follow**<br />\* **track**<br />\* **locations**               | No required parameters for streaming connection, optional backfill parameter.<br /><br />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.<br /><br />Rules managed separately                                                                                                                                                                                                                                                                                                                                                                 |
| Delivery type                                                                   | Streaming                                                                                                                                | Streaming<br /><br />REST (for rules management)                                                                                                                                                                                | Streaming<br /><br />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<br /><br />/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<br /><br />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:<br /><br />- 400 track keywords<br /><br />- 5000 follow user IDs<br /><br />- 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)<br /><br />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<br /><br />No configuration UI                                                 | Filtering done via rules created through an independent endpoint<br /><br />[Enrichment](/x-api/enterprise-gnip-2.0/enterprise-gnip#enrichments) features available in contract<br /><br />Configuration on console.gnip.com UI | Filtering done via [rules](/x-api/posts/filtered-stream/integrate/build-a-rule) created through an independent endpoint<br /><br />[Metrics](/x-api/fundamentals/metrics) and URL enrichment features included<br /><br />Object [fields](/x-api/fundamentals/fields) and  [expansions](/x-api/fundamentals/expansions) specified with request parameters<br /><br />Post [Annotations](/x-api/fundamentals/post-annotations)<br /><br />[Conversation ID](/x-api/fundamentals/conversation-id) operator and field<br /><br />Configuration through [Developer Console](/resources/fundamentals/developer-portal) |


# v1 to v2 (Enterprise)
Source: https://docs.x.com/x-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2

Use this migration guide to understand the similarities and differences between PowerTrack API. Reference for the X API v2 standard tier covering migrate.

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


# v1 to v2
Source: https://docs.x.com/x-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2

If you have been working with the v1.1 statuses/filter endpoint, this guide can help you. Reference for the X API v2 standard tier covering migrate.

### 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:<br /><br />\* @<br />\* from:<br />\* to:<br />\* 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:<br /><br />\* keyword<br />\* "exact phrase match"<br />\* #<br />\* 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](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)
  * [https://api.x.com/2/tweets/search/stream/rule](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 support [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 an 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 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/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/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. 
* 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/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
* 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.<br /><br />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. <br /><br />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.


# Quickstart
Source: https://docs.x.com/x-api/posts/filtered-stream/quickstart

This guide walks you through connecting to the filtered stream to receive near real-time. Reference for the X API v2 standard tier covering filtered stream.

This guide walks you through connecting to the filtered stream to receive near real-time Posts matching your filter rules.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * Your App's Bearer Token (found in the Developer Console under "Keys and tokens")
</Note>

***

<Steps>
  <Step title="Create a filter rule" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e">
    Rules define which Posts to receive. Use operators to match on keywords, hashtags, users, and more.

    **Example rule:** Match Posts containing "cat" with images:

    ```
    cat has:images
    ```

    <Card title="Build a rule" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e" href="/x-api/posts/filtered-stream/integrate/build-a-rule">
      Learn rule syntax and operators
    </Card>
  </Step>

  <Step title="Add the rule to your stream" icon="plus">
    Add your rule using the rules endpoint. Include a `tag` to identify which rule matched each Post:

    <CodeGroup>
      ```bash cURL theme={null}
      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 SDK theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Add a rule to the filtered stream
      response = client.filtered_stream.add_rules(
          add=[{"value": "cat has:images", "tag": "cats with images"}]
      )

      for rule in response.data:
          print(f"Rule added: {rule.id} - {rule.value}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Add a rule to the filtered stream
      const response = await client.filteredStream.addRules({
        add: [{ value: "cat has:images", tag: "cats with images" }],
      });

      response.data?.forEach((rule) => {
        console.log(`Rule added: ${rule.id} - ${rule.value}`);
      });
      ```
    </CodeGroup>

    **Response:**

    ```json theme={null}
    {
      "data": [
        {
          "id": "1273026480692322304",
          "value": "cat has:images",
          "tag": "cats with images"
        }
      ],
      "meta": {
        "sent": "2024-01-15T10:30:00.000Z",
        "summary": {
          "created": 1,
          "not_created": 0,
          "valid": 1,
          "invalid": 0
        }
      }
    }
    ```
  </Step>

  <Step title="Verify your rules" icon="check">
    List all active rules to confirm your rule was added:

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/tweets/search/stream/rules" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python Python SDK theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Get all active rules
      response = client.filtered_stream.get_rules()

      for rule in response.data:
          print(f"Active rule: {rule.id} - {rule.value}")
      ```

      ```javascript JavaScript SDK theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Get all active rules
      const response = await client.filteredStream.getRules();

      response.data?.forEach((rule) => {
        console.log(`Active rule: ${rule.id} - ${rule.value}`);
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Connect to the stream" icon="plug">
    Open a persistent connection to receive matching Posts:

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/tweets/search/stream?\
      tweet.fields=created_at,author_id&\
      expansions=author_id&\
      user.fields=username" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Connect to the filtered stream
      for post in client.filtered_stream.stream(
          tweet_fields=["created_at", "author_id"],
          expansions=["author_id"],
          user_fields=["username"]
      ):
          print(f"New post: {post.data.text}")
          print(f"Matching rules: {post.matching_rules}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Connect to the filtered stream
      const stream = client.filteredStream.stream({
        tweetFields: ["created_at", "author_id"],
        expansions: ["author_id"],
        userFields: ["username"],
      });

      for await (const post of stream) {
        console.log(`New post: ${post.data?.text}`);
        console.log(`Matching rules: ${post.matching_rules}`);
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Process incoming Posts" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f">
    Matching Posts stream as JSON objects:

    ```json theme={null}
    {
      "data": {
        "id": "1234567890",
        "text": "Look at this cute cat! 🐱",
        "author_id": "9876543210",
        "created_at": "2024-01-15T10:35:00.000Z",
        "edit_history_tweet_ids": ["1234567890"]
      },
      "includes": {
        "users": [
          {
            "id": "9876543210",
            "username": "catperson"
          }
        ]
      },
      "matching_rules": [
        {
          "id": "1273026480692322304",
          "tag": "cats with images"
        }
      ]
    }
    ```

    <Tip>
      The `matching_rules` array shows which rules matched the Post, using the tags you defined.
    </Tip>
  </Step>

  <Step title="Delete rules (optional)" icon="trash">
    Remove rules by their ID:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
        -H "Authorization: Bearer $BEARER_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "delete": {
            "ids": ["1273026480692322304"]
          }
        }'
      ```

      ```python Python SDK theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Delete rules by ID
      response = client.filtered_stream.delete_rules(
          delete={"ids": ["1273026480692322304"]}
      )
      print(f"Deleted: {response.meta.summary.deleted}")
      ```

      ```javascript JavaScript SDK theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Delete rules by ID
      const response = await client.filteredStream.deleteRules({
        delete: { ids: ["1273026480692322304"] },
      });
      console.log(`Deleted: ${response.meta?.summary?.deleted}`);
      ```
    </CodeGroup>
  </Step>
</Steps>

***

## Managing your connection

<AccordionGroup>
  <Accordion title="Keep-alive signals">
    The stream sends blank lines (`\r\n`) every 20 seconds. If you don't receive data or a keep-alive for 20 seconds, reconnect.
  </Accordion>

  <Accordion title="Disconnecting">
    Press `Ctrl+C` to close the connection, or close your terminal window.
  </Accordion>

  <Accordion title="Connection limits">
    Only one connection per App is allowed. Opening a new connection will close any existing one.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup>
  <Card title="Build a rule" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e" href="/x-api/posts/filtered-stream/integrate/build-a-rule">
    Learn rule syntax
  </Card>

  <Card title="Operator reference" icon="list-check" href="/x-api/posts/filtered-stream/integrate/operators">
    All available operators
  </Card>

  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Reconnect gracefully
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/filtered-stream">
    Full endpoint documentation
  </Card>
</CardGroup>


# Get 28 hour post insights
Source: https://docs.x.com/x-api/posts/get-28-hour-post-insights

get /2/insights/28hr



# Get Posts Counts All
Source: https://docs.x.com/x-api/posts/get-count-of-all-posts

get /2/tweets/counts/all
At most one of `pagination_token`, `next_token` may be provided.



# Get Posts Counts Recent
Source: https://docs.x.com/x-api/posts/get-count-of-recent-posts

get /2/tweets/counts/recent
At most one of `pagination_token`, `next_token` may be provided.



# Get historical post insights
Source: https://docs.x.com/x-api/posts/get-historical-post-insights

get /2/insights/historical



# Get Posts Liking Users
Source: https://docs.x.com/x-api/posts/get-liking-users

get /2/tweets/{id}/liking_users



# Get Posts Analytics
Source: https://docs.x.com/x-api/posts/get-post-analytics

get /2/tweets/analytics



# Get Posts by ID
Source: https://docs.x.com/x-api/posts/get-post-by-id

get /2/tweets/{id}



# Get Posts Analytics
Source: https://docs.x.com/x-api/posts/get-posts-analytics

get /2/tweets/analytics



# Get Posts by ID
Source: https://docs.x.com/x-api/posts/get-posts-by-id

get /2/tweets/{id}



# Get Posts by IDs
Source: https://docs.x.com/x-api/posts/get-posts-by-ids

get /2/tweets



# Get Posts Counts All
Source: https://docs.x.com/x-api/posts/get-posts-counts-all

get /2/tweets/counts/all
At most one of `pagination_token`, `next_token` may be provided.



# Get Posts Counts Recent
Source: https://docs.x.com/x-api/posts/get-posts-counts-recent

get /2/tweets/counts/recent
At most one of `pagination_token`, `next_token` may be provided.



# Get Posts Liking Users
Source: https://docs.x.com/x-api/posts/get-posts-liking-users

get /2/tweets/{id}/liking_users



# Get Posts Quoted Posts
Source: https://docs.x.com/x-api/posts/get-posts-quoted-posts

get /2/tweets/{id}/quote_tweets



# Get Posts Reposted by
Source: https://docs.x.com/x-api/posts/get-posts-reposted-by

get /2/tweets/{id}/retweeted_by



# Get Posts Reposts
Source: https://docs.x.com/x-api/posts/get-posts-reposts

get /2/tweets/{id}/retweets



# Get Posts Quoted Posts
Source: https://docs.x.com/x-api/posts/get-quoted-posts

get /2/tweets/{id}/quote_tweets



# Get Posts Reposted by
Source: https://docs.x.com/x-api/posts/get-reposted-by

get /2/tweets/{id}/retweeted_by



# Get Posts Reposts
Source: https://docs.x.com/x-api/posts/get-reposts

get /2/tweets/{id}/retweets



# Apps
Source: https://docs.x.com/x-api/posts/hide-replies/apps

Here's a collection of noteworthy apps built by developers who integrated the hide replies. Reference for the X API v2 standard tier covering hide replies.

## 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=%22[http://www.w3.org/2000/svg%22](http://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=%22[http://www.w3.org/2000/svg%22](http://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=%22[http://www.w3.org/2000/svg%22](http://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")


# Manage replies by topic
Source: https://docs.x.com/x-api/posts/hide-replies/integrate/manage-replies-by-topic

Through the hide replies endpoint, you can build integrations to help people and brands keep. Reference for the X API v2 standard tier covering integrate.

### 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.


# Manage replies by topic
Source: https://docs.x.com/x-api/posts/hide-replies/integrate/manage-replies-in-realtime

With the hide replies endpoint, you can build a workflow to help your users hide replies that. Reference for the X API v2 standard tier covering integrate.

### Manage replies in realtime

With the hide replies endpoint, you can build a workflow to help 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.


# Hide Replies
Source: https://docs.x.com/x-api/posts/hide-replies/introduction

Use the X API v2 Hide Replies endpoint to hide or unhide replies to Posts authored by the authenticated user and moderate conversations on X.

The Hide Replies endpoint lets you hide or unhide replies to Posts authored by the authenticated user. Hidden replies are still accessible but require an extra click to view.

## Overview

<CardGroup>
  <Card title="Hide reply" icon="eye-slash">
    Hide a reply to your Post
  </Card>

  <Card title="Unhide reply" icon="eye">
    Unhide a previously hidden reply
  </Card>

  <Card title="Conversation control" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=ce6313d8c0b7b4e5363f2ce80b89f7e4">
    Moderate discussions on your Posts
  </Card>
</CardGroup>

***

## Endpoint

| Method | Endpoint                                                | Description            |
| :----- | :------------------------------------------------------ | :--------------------- |
| PUT    | [`/2/tweets/:tweet_id/hidden`](/x-api/posts/hide-reply) | Hide or unhide a reply |

***

## How it works

Send a PUT request with `hidden: true` to hide a reply, or `hidden: false` to unhide it:

```json theme={null}
{
  "hidden": true
}
```

***

## Example: Hide a reply

```bash theme={null}
curl -X PUT "https://api.x.com/2/tweets/1234567890/hidden" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hidden": true}'
```

## Example response

```json theme={null}
{
  "data": {
    "hidden": true
  }
}
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * User Access Tokens via [OAuth 2.0 PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/hide-replies/quickstart">
    Hide your first reply
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/hide-replies">
    Full endpoint documentation
  </Card>
</CardGroup>


# Migration guide
Source: https://docs.x.com/x-api/posts/hide-replies/migrate

The v2 hide replies endpoint is replacing the Labs hide replies endpoint. Reference for the X API v2 standard tier covering hide replies.

## 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)                             | [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)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.x.com/2/tweets/1234567890/hidden" \
    -H "Authorization: OAuth ..." \
    -H "Content-Type: application/json" \
    -d '{"hidden": true}'
  ```

  ```python title="Python" lines wrap icon="python" theme={null}
  # 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 title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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}`);
  ```
</CodeGroup>

**Other migration resources**

[X API migration hub](/x-api/migrate/overview)


# Quickstart
Source: https://docs.x.com/x-api/posts/hide-replies/quickstart

This guide walks you through hiding and unhiding replies to Posts in conversations you. Reference for the X API v2 standard tier covering hide replies.

This guide walks you through hiding and unhiding replies to Posts in conversations you started.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Hide a reply

<Steps>
  <Step title="Find the reply's Post ID" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f">
    Get the ID of the reply you want to hide. You can only hide replies to conversations started by the authenticated user.

    ```
    https://x.com/user/status/1232720193182412800
                              └── This is the Post ID
    ```
  </Step>

  <Step title="Send the hide request" icon="eye-slash">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X PUT "https://api.x.com/2/tweets/1232720193182412800/hidden" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"hidden": true}'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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("1232720193182412800", hidden=True)
      print(f"Hidden: {response.data.hidden}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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("1232720193182412800", {
        hidden: true,
      });
      console.log(`Hidden: ${response.data?.hidden}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Confirm the reply is hidden" icon="check">
    ```json theme={null}
    {
      "data": {
        "hidden": true
      }
    }
    ```

    The reply is now hidden from the main conversation view. Users can still see it by clicking "View hidden replies."
  </Step>
</Steps>

***

## Unhide a reply

To make a hidden reply visible again:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.x.com/2/tweets/1232720193182412800/hidden" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"hidden": false}'
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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)

  # Unhide a reply
  response = client.posts.hide_reply("1232720193182412800", hidden=False)
  print(f"Hidden: {response.data.hidden}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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 });

  // Unhide a reply
  const response = await client.posts.hideReply("1232720193182412800", {
    hidden: false,
  });
  console.log(`Hidden: ${response.data?.hidden}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "hidden": false
  }
}
```

***

## Important notes

<Note>
  * You can only hide replies to conversations **you started**
  * Hidden replies are still visible via "View hidden replies"
  * The reply author is not notified when their reply is hidden
</Note>

***

## Next steps

<CardGroup>
  <Card title="Manage by topic" icon="tags" href="/x-api/posts/hide-replies/integrate/manage-replies-by-topic">
    Moderate replies based on content
  </Card>

  <Card title="Real-time moderation" icon="bolt" href="/x-api/posts/hide-replies/integrate/manage-replies-in-realtime">
    Moderate replies as they arrive
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/hide-reply">
    Full endpoint documentation
  </Card>
</CardGroup>


# Hide reply
Source: https://docs.x.com/x-api/posts/hide-reply

put /2/tweets/{tweet_id}/hidden
Hides or unhides a reply to a conversation owned by the authenticated user.



# Likes
Source: https://docs.x.com/x-api/posts/likes/introduction

The Likes endpoints let you like and unlike Posts, see which users liked a Post, and get Posts. Reference for the X API v2 standard tier covering likes.

The Likes endpoints let you like and unlike Posts, see which users liked a Post, and get Posts liked by a user.

## Overview

<CardGroup>
  <Card title="Like a Post" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-heart.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=3a435e6393c019d681c6f1a0737e21a8">
    Like a Post on behalf of a user
  </Card>

  <Card title="Unlike a Post" icon="heart-crack">
    Remove a like from a Post
  </Card>

  <Card title="Liking users" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980">
    See who liked a Post
  </Card>

  <Card title="Liked Posts" icon="list-heart">
    Get Posts a user has liked
  </Card>
</CardGroup>

***

## Endpoints

### Likes lookup

| Method | Endpoint                                                      | Description                |
| :----- | :------------------------------------------------------------ | :------------------------- |
| GET    | [`/2/tweets/:id/liking_users`](/x-api/posts/get-liking-users) | Get users who liked a Post |
| GET    | [`/2/users/:id/liked_tweets`](/x-api/users/get-liked-posts)   | Get Posts liked by a user  |

### Manage likes

| Method | Endpoint                                                   | Description   |
| :----- | :--------------------------------------------------------- | :------------ |
| POST   | [`/2/users/:id/likes`](/x-api/users/like-post)             | Like a Post   |
| DELETE | [`/2/users/:id/likes/:tweet_id`](/x-api/users/unlike-post) | Unlike a Post |

***

## Important notes

<Note>
  The liking users endpoint returns a maximum of **100 users** per Post for all time, regardless of the actual number of likes.
</Note>

***

## Example: Get liking users

```bash theme={null}
curl "https://api.x.com/2/tweets/1234567890/liking_users?\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

## Example: Like a Post

```bash theme={null}
curl -X POST "https://api.x.com/2/users/123456789/likes" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tweet_id": "1234567890"}'
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Lookup quickstart" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-heart.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=3a435e6393c019d681c6f1a0737e21a8" href="/x-api/posts/likes/quickstart/likes-lookup">
    Get likes for a Post
  </Card>

  <Card title="Manage quickstart" icon="plus" href="/x-api/posts/likes/quickstart/manage-likes">
    Like and unlike Posts
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/get-liking-users">
    Full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# Likes lookup
Source: https://docs.x.com/x-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2

If you have been working with the standard v1.1 GET favorites/list endpoint, the goal of this. Reference for the X API v2 standard tier covering migrate.

### 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**
  * Authentication
  * 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


# Manage Likes
Source: https://docs.x.com/x-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2

If you have been working with the standard v1.1 POST favorites/create and POST favorites/destroy. Reference for the X API v2 standard tier covering migrate.

### 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](https://api.x.com/1.1/favorites/create.json)
    (like a Post)
  * POST [https://api.x.com/1.1/favorites/destroy.json](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](https://api.x.com/2/tweets/:id/likes)
    (like a Post)
  * DELETE [https://api.x.com/2/tweets/:id/likes/:tweet\_id](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


# Likes endpoints migration overview
Source: https://docs.x.com/x-api/posts/likes/migrate/overview

Map Standard v1.1 Likes endpoints (favorites/list, favorites/create, favorites/destroy) to X API v2 likes endpoints to plan a migration.

## 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](https://api.x.com)                                        |
| Endpoint path                                                      | /2/tweets/:id/liking\_users                                                   |
| [Authentication](/resources/fundamentals/authentication)           | OAuth 2.0 Bearer Token<br /><br />OAuth 1.0a User Context                     |
| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min (per App)<br /><br />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) | [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<br /><br />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)<br /><br />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)<br /><br />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)                                                | [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)<br /><br />1000 requests per 24 hours (per App) | 50 requests per 15 min (per user)<br /><br />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)                                                | [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)<br /><br />1000 requests per 24 hours (per App) | 50 requests per 15 min (per user)<br /><br />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)


# Likes Lookup
Source: https://docs.x.com/x-api/posts/likes/quickstart/likes-lookup

Quickstart for retrieving like data from the X API, including liking users and liked Posts, using the X API v2 standard tier likes lookup endpoints.

This guide walks you through retrieving likes data using the X API.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token (for public data) or User Access Token (for private metrics)
</Note>

***

## Get users who liked a Post

Retrieve the list of users who liked a specific Post:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/tweets/1354143047324299264/liking_users?\
  user.fields=created_at,username,verified" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get users who liked a Post with pagination
  for page in client.posts.get_liking_users(
      "1354143047324299264",
      user_fields=["created_at", "username", "verified"]
  ):
      for user in page.data:
          print(f"{user.username} - Joined: {user.created_at}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get users who liked a Post with pagination
  const paginator = client.posts.getLikingUsers("1354143047324299264", {
    userFields: ["created_at", "username", "verified"],
  });

  for await (const page of paginator) {
    page.data?.forEach((user) => {
      console.log(`${user.username} - Joined: ${user.created_at}`);
    });
  }
  ```
</CodeGroup>

### Response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "created_at": "2008-12-04T18:51:57.000Z",
      "id": "17874544",
      "username": "TwitterSupport",
      "name": "Twitter Support",
      "verified": true
    },
    {
      "created_at": "2007-02-20T14:35:54.000Z",
      "id": "783214",
      "username": "Twitter",
      "name": "Twitter",
      "verified": true
    }
  ],
  "meta": {
    "result_count": 2,
    "next_token": "7140dibdnow9c7btw3z2vwioavpvutgzrzm9icis4ndix"
  }
}
```

***

## Get a user's liked Posts

Retrieve Posts that a specific user has liked:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/2244994945/liked_tweets?\
  tweet.fields=created_at,public_metrics&\
  max_results=10" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get a user's liked Posts with pagination
  for page in client.users.get_liked_tweets(
      "2244994945",
      tweet_fields=["created_at", "public_metrics"],
      max_results=10
  ):
      for post in page.data:
          print(f"{post.text[:50]}... - Likes: {post.public_metrics.like_count}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get a user's liked Posts with pagination
  const paginator = client.users.getLikedTweets("2244994945", {
    tweetFields: ["created_at", "public_metrics"],
    maxResults: 10,
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(`${post.text?.slice(0, 50)}... - Likes: ${post.public_metrics?.like_count}`);
    });
  }
  ```
</CodeGroup>

### Response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "1362449997430542337",
      "text": "Honored to be the first developer to be featured...",
      "created_at": "2021-02-18T17:45:00.000Z",
      "public_metrics": {
        "retweet_count": 5,
        "reply_count": 2,
        "like_count": 42,
        "quote_count": 1
      }
    }
  ],
  "meta": {
    "result_count": 1,
    "next_token": "7140dibdnow9c7btw4539n0vybdnx19ylpayqf16fjt4l"
  }
}
```

***

## Include additional data

Use expansions to get related data like pinned Posts:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/tweets/1354143047324299264/liking_users?\
  user.fields=created_at&\
  expansions=pinned_tweet_id&\
  tweet.fields=created_at" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get liking users with pinned Post expansion
  for page in client.posts.get_liking_users(
      "1354143047324299264",
      user_fields=["created_at"],
      expansions=["pinned_tweet_id"],
      tweet_fields=["created_at"]
  ):
      for user in page.data:
          print(f"{user.username}")
      # Pinned Posts are in page.includes.tweets
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get liking users with pinned Post expansion
  const paginator = client.posts.getLikingUsers("1354143047324299264", {
    userFields: ["created_at"],
    expansions: ["pinned_tweet_id"],
    tweetFields: ["created_at"],
  });

  for await (const page of paginator) {
    page.data?.forEach((user) => {
      console.log(user.username);
    });
    // Pinned Posts are in page.includes?.tweets
  }
  ```
</CodeGroup>

***

## Next steps

<CardGroup>
  <Card title="Manage likes" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-heart.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=3a435e6393c019d681c6f1a0737e21a8" href="/x-api/posts/likes/quickstart/manage-likes">
    Like and unlike Posts
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/get-liking-users">
    Full endpoint documentation
  </Card>
</CardGroup>


# Manage Likes
Source: https://docs.x.com/x-api/posts/likes/quickstart/manage-likes

This guide walks you through liking and unliking Posts using the X API. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through liking and unliking Posts using the X API.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Like a Post

<Steps>
  <Step title="Get your user ID">
    You need your authenticated user's ID. You can find it using the [user lookup endpoint](/x-api/users/lookup/introduction) or from your Access Token (the numeric part is your user ID).
  </Step>

  <Step title="Get the Post ID">
    Find the Post ID in the URL when viewing a Post:

    ```
    https://x.com/XDevelopers/status/1228393702244134912
                                    └── This is the Post ID
    ```
  </Step>

  <Step title="Send the like request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/users/123456789/likes" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"tweet_id": "1228393702244134912"}'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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="1228393702244134912"
      )

      print(f"Liked: {response.data.liked}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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: "1228393702244134912",
      });

      console.log(`Liked: ${response.data?.liked}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": {
        "liked": true
      }
    }
    ```
  </Step>
</Steps>

***

## Unlike a Post

Remove a like from a Post:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.x.com/2/users/123456789/likes/1228393702244134912" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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="1228393702244134912"
  )

  print(f"Liked: {response.data.liked}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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", "1228393702244134912");

  console.log(`Liked: ${response.data?.liked}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "liked": false
  }
}
```

***

## Next steps

<CardGroup>
  <Card title="Likes lookup" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-heart.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=3a435e6393c019d681c6f1a0737e21a8" href="/x-api/posts/likes/quickstart/likes-lookup">
    Get users who liked a Post
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/like-post">
    Full endpoint documentation
  </Card>
</CardGroup>


# Integration Guide
Source: https://docs.x.com/x-api/posts/lookup/integrate

This guide covers the key concepts you need to integrate the Post lookup endpoints into your. Reference for the X API v2 standard tier covering lookup.

This guide covers the key concepts you need to integrate the Post 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 Posts) |
| [OAuth 1.0a User Context](/resources/fundamentals/authentication)                                                              | Legacy integrations           | Yes (for authorized user's Posts) |

### App-Only authentication

For public Post data, use a Bearer Token:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/tweets/1234567890" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get a single Post by ID
  response = client.posts.get("1234567890")
  print(response.data)
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  const response = await client.posts.get("1234567890");
  console.log(response.data);
  ```
</CodeGroup>

### User Context authentication

To access private metrics, authenticate on behalf of the Post author:

<Warning>
  The following fields require User Context authentication:

  * `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`
</Warning>

***

## 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 theme={null}
{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "edit_history_tweet_ids": ["1234567890"]
  }
}
```

### Available fields

<Accordion title="tweet.fields">
  | Field                 | Description                        |
  | :-------------------- | :--------------------------------- |
  | `created_at`          | Post creation timestamp            |
  | `author_id`           | Author's user ID                   |
  | `public_metrics`      | Like, retweet, reply, quote counts |
  | `entities`            | Hashtags, mentions, URLs, cashtags |
  | `attachments`         | Media keys, poll IDs               |
  | `conversation_id`     | Thread identifier                  |
  | `context_annotations` | Topic/entity classifications       |
  | `in_reply_to_user_id` | User being replied to              |
  | `lang`                | Detected language                  |
  | `source`              | Posting client                     |
  | `possibly_sensitive`  | Sensitive content flag             |
  | `reply_settings`      | Who can reply                      |
</Accordion>

<Accordion title="user.fields (requires author_id expansion)">
  | Field               | Description               |
  | :------------------ | :------------------------ |
  | `username`          | @handle                   |
  | `name`              | Display name              |
  | `profile_image_url` | Avatar URL                |
  | `verified`          | Verification status       |
  | `description`       | Bio                       |
  | `public_metrics`    | Follower/following counts |
  | `created_at`        | Account creation date     |
</Accordion>

<Accordion title="media.fields (requires attachments.media_keys expansion)">
  | Field               | Description                 |
  | :------------------ | :-------------------------- |
  | `url`               | Media URL                   |
  | `preview_image_url` | Thumbnail URL               |
  | `type`              | photo, video, animated\_gif |
  | `duration_ms`       | Video duration              |
  | `height`, `width`   | Dimensions                  |
  | `alt_text`          | Accessibility text          |
</Accordion>

### Example with fields

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/tweets/1234567890?\
  tweet.fields=created_at,public_metrics,entities&\
  expansions=author_id,attachments.media_keys&\
  user.fields=username,verified&\
  media.fields=url,type" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get a Post with additional fields and expansions
  response = client.posts.get(
      "1234567890",
      tweet_fields=["created_at", "public_metrics", "entities"],
      expansions=["author_id", "attachments.media_keys"],
      user_fields=["username", "verified"],
      media_fields=["url", "type"]
  )

  print(response.data)
  print(response.includes)  # Contains expanded user and media objects
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  const response = await client.posts.get("1234567890", {
    tweetFields: ["created_at", "public_metrics", "entities"],
    expansions: ["author_id", "attachments.media_keys"],
    userFields: ["username", "verified"],
    mediaFields: ["url", "type"],
  });

  console.log(response.data);
  console.log(response.includes); // Contains expanded user and media objects
  ```
</CodeGroup>

***

## Post edits

Posts can be edited up to 5 times within 30 minutes of creation.

### How it works

* Each edit creates a new Post ID
* `edit_history_tweet_ids` contains all versions (oldest first)
* The endpoint always returns the most recent version

### Example response

```json theme={null}
{
  "data": {
    "id": "1234567893",
    "text": "Hello world! (edited twice)",
    "edit_history_tweet_ids": [
      "1234567890",
      "1234567891",
      "1234567893"
    ]
  }
}
```

<Tip>
  Posts retrieved after their 30-minute edit window represent the final version. For real-time use cases, be aware that recently-published Posts may still be edited.
</Tip>

***

## 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         | Post deleted or doesn't exist     |
| 429    | Too Many Requests | Wait and retry (see rate limits)  |

### Deleted or protected Posts

If a Post is deleted or from a protected account you don't follow:

* Single Post lookup returns `404`
* Multi-Post lookup omits the Post from results with an `errors` array

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    { "id": "1234567890", "text": "Available post" }
  ],
  "errors": [
    {
      "resource_id": "1234567891",
      "resource_type": "tweet",
      "title": "Not Found Error",
      "detail": "Could not find tweet with id: [1234567891]."
    }
  ]
}
```

***

## Best practices

<CardGroup>
  <Card title="Batch requests" icon="layer-group">
    Use the multi-Post endpoint to fetch up to 100 Posts at once, reducing API calls.
  </Card>

  <Card title="Request only needed fields" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e">
    Specify only the fields you need to minimize response size and processing time.
  </Card>

  <Card title="Cache responses" icon="database">
    Cache Post data locally to reduce repeated requests for the same content.
  </Card>

  <Card title="Handle edits" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-history.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=6afe17587c08ee621e37afde19a07ff1">
    For real-time apps, consider re-fetching Posts after the 30-minute edit window.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/post-lookup-by-post-id">
    Complete endpoint documentation
  </Card>

  <Card title="Data dictionary" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/fundamentals/data-dictionary">
    All available objects and fields
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>

  <Card title="Error handling" icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" href="/x-api/fundamentals/response-codes-and-errors">
    Handle errors gracefully
  </Card>
</CardGroup>


# Post Lookup
Source: https://docs.x.com/x-api/posts/lookup/introduction

The Post lookup endpoints allow you to retrieve one or more Posts by their IDs. Reference for the X API v2 standard tier covering lookup.

The Post lookup endpoints allow you to retrieve one or more Posts by their IDs. Use these endpoints to get up-to-date Post details, verify Post availability, or examine edit history.

## Overview

Posts are the core content on X. Each Post can contain:

* Up to 280 characters of text
* Attached media (images, videos, GIFs)
* Polls, places, and URLs
* Replies, quotes, and mentions

Posts can be edited up to 5 times within 30 minutes of creation. Each edit generates a new Post ID, and the edit history is preserved.

<CardGroup>
  <Card title="Single Post" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f">
    Retrieve a specific Post by ID
  </Card>

  <Card title="Multiple Posts" icon="messages">
    Retrieve up to 100 Posts in one request
  </Card>

  <Card title="Edit History" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-history.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=6afe17587c08ee621e37afde19a07ff1">
    Access the complete edit history of a Post
  </Card>

  <Card title="Expanded Objects" icon="diagram-project">
    Include author, media, polls, and more
  </Card>
</CardGroup>

***

## Use cases

* **Display Post content** — Show Post details in your application
* **Verify availability** — Check if a Post still exists or was deleted
* **Compliance management** — Track Post changes for compliance events
* **Analytics** — Retrieve engagement metrics for specific Posts

***

## Endpoints

| Method | Endpoint                                       | Description                                |
| :----- | :--------------------------------------------- | :----------------------------------------- |
| GET    | [`/2/tweets/:id`](/x-api/posts/get-post-by-id) | Retrieve a single Post by ID               |
| GET    | [`/2/tweets`](/x-api/posts/get-posts-by-ids)   | Retrieve multiple Posts by IDs (up to 100) |

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/lookup/quickstart">
    Make your first Post lookup request
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/lookup/integrate">
    Learn key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/get-post-by-id">
    See full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Explore code examples
  </Card>
</CardGroup>


# Overview
Source: https://docs.x.com/x-api/posts/lookup/migrate/overview

The v2 Posts lookup endpoints replace the standard v1.1 GET statuses/lookup and GET statuses/show. Reference for the X API v2 standard tier covering migrate.

## 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.

## Endpoint comparison table

| 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/statuses/show.json`, `/1.1/statuses/lookup.json` | `/2/tweets`                                                                                                                                    |
| **[Authentication](resources/fundamentals/authentication)**                                             | OAuth 1.0a User Context                                | OAuth 1.0a User Context, OAuth 2.0 App-Only, OAuth 2.0 Authorization Code with PKCE                                                            |
| **Post [JSON format](/x-api/fundamentals/data-dictionary)**                                             | Standard v1.1 format                                   | [X API v2 format](/x-api/fundamentals/data-dictionary), determined by `fields` and `expansions` parameters (not backward-compatible with v1.1) |
| **Supports selecting specific [fields](/x-api/fundamentals/data-dictionary)**                           |                                                        | ✔                                                                                                                                              |
| **Supports the [annotations](/x-api/fundamentals/post-annotations) fields**                             |                                                        | ✔                                                                                                                                              |
| **Supports new [metrics](/x-api/fundamentals/metrics) fields**                                          |                                                        | ✔                                                                                                                                              |
| **Supports `conversation_id` field**                                                                    |                                                        | ✔                                                                                                                                              |
| **Provides Post edit history**                                                                          | ✔                                                      | ✔                                                                                                                                              |
| **Requires credentials from a [developer App](/fundamentals/developer-apps) associated with a Project** |                                                        | ✔                                                                                                                                              |

***

## 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.

You may also be interested in our [visual data format migration tool](/x-api/migrate/data-format-migration) to help you quickly see the differences between the [X API v1.1 data format](/x-api/fundamentals/data-dictionary) and the [X API v2 format](/x-api/fundamentals/data-dictionary).

* **Similarities**
  * OAuth 1.0a User Context
  * Posts per request limits
  * Support for Post edit history and metadata

* **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), while the new X API v2 Post lookup endpoint supports both OAuth 1.0a User Context and [OAuth 2.0 App-Only](/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 Post lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version.

App-Only authentication is likely the easiest way to get started. To learn how to generate an App Access Token, see [this OAuth 2.0 App-only guide](/resources/fundamentals/authentication).

#### 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/fields) 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. |

### CURL Requests

The following cURL requests show standard v1.1 endpoints and their v2 equivalents. Replace `ACCESS_TOKEN` in the header with your app access token. For v2 endpoints, the token must belong to a [developer App](/fundamentals/developer-apps) within a Project.

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.

**Standard v1.1 `GET statuses/lookup` and v2 `GET /tweets` endpoints**

```bash theme={null}
curl --request GET \
  --url 'https://api.x.com/1.1/statuses/lookup.json?id=1460323737035677698%2C1460323743339741184' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'
```

```bash theme={null}
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'
```

**Standard v1.1 `GET statuses/show/:id` and v2 `GET /tweets/:id` endpoints**

```bash theme={null}
curl --request GET \
  --url 'https://api.x.com/1.1/statuses/show.json?id=1460323737035677698' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'
```

```bash theme={null}
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'
```


# v1 to v2
Source: https://docs.x.com/x-api/posts/lookup/migrate/standard-to-twitter-api-v2

If you have been working with the standard v1.1 GET statuses/show and GET statuses/lookup, this. Reference for the X API v2 standard tier covering migrate.

## 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.

You may also be interested in our [visual data format migration tool](/x-api/migrate/data-format-migration) to help you quickly see the differences between the [X API v1.1 data format](/x-api/fundamentals/data-dictionary) and the [X API v2 format](/x-api/fundamentals/data-dictionary).

* **Similarities**
  * OAuth 1.0a User Context
  * Posts per request limits
  * Support for Post edit history and metadata

* **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), while the new X API v2 Post lookup endpoint supports both OAuth 1.0a User Context and [OAuth 2.0 App-Only](/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 Post lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version.

App-Only authentication is likely the easiest way to get started. To learn how to generate an App Access Token, see [this OAuth 2.0 App-only guide](/resources/fundamentals/authentication).

#### 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 wi


# Quickstart
Source: https://docs.x.com/x-api/posts/lookup/quickstart

This guide walks you through making your first Post lookup request using the X API v2. Reference for the X API v2 standard tier covering lookup.

This guide walks you through making your first Post lookup request using the X API v2.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token (found in the Developer Console under "Keys and tokens")
</Note>

***

<Steps>
  <Step title="Find a Post ID">
    Every Post has a unique ID. You can find it in the Post's URL:

    ```
    https://x.com/XDevelopers/status/1228393702244134912
                                    └── This is the Post ID
    ```
  </Step>

  <Step title="Make a request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/tweets/1228393702244134912" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python Python SDK theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Get a single Post by ID
      response = client.posts.get("1228393702244134912")
      print(response.data)
      ```

      ```javascript JavaScript SDK theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      const response = await client.posts.get("1228393702244134912");
      console.log(response.data);
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    The default response includes the Post's `id`, `text`, and `edit_history_tweet_ids`:

    ```json theme={null}
    {
      "data": {
        "id": "1228393702244134912",
        "text": "What did the developer write in their Valentine's card?\n\nwhile(true) {\n    I = Love(You);\n}",
        "edit_history_tweet_ids": ["1228393702244134912"]
      }
    }
    ```
  </Step>

  <Step title="Request additional fields">
    Use query parameters to get more data:

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/tweets/1228393702244134912?\
      tweet.fields=created_at,public_metrics,author_id&\
      expansions=author_id&\
      user.fields=username,verified" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Get a Post with additional fields and expansions
      response = client.posts.get(
          "1228393702244134912",
          tweet_fields=["created_at", "public_metrics", "author_id"],
          expansions=["author_id"],
          user_fields=["username", "verified"]
      )

      print(response.data)
      print(response.includes)  # Contains author user object
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      const response = await client.posts.get("1228393702244134912", {
        tweetFields: ["created_at", "public_metrics", "author_id"],
        expansions: ["author_id"],
        userFields: ["username", "verified"],
      });

      console.log(response.data);
      console.log(response.includes); // Contains author user object
      ```
    </CodeGroup>

    **Response:**

    ```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "data": {
        "id": "1228393702244134912",
        "text": "What did the developer write in their Valentine's card?...",
        "created_at": "2020-02-14T19:00:55.000Z",
        "author_id": "2244994945",
        "public_metrics": {
          "retweet_count": 156,
          "reply_count": 23,
          "like_count": 892,
          "quote_count": 12
        },
        "edit_history_tweet_ids": ["1228393702244134912"]
      },
      "includes": {
        "users": [
          {
            "id": "2244994945",
            "username": "XDevelopers",
            "verified": true
          }
        ]
      }
    }
    ```
  </Step>

  <Step title="Look up multiple Posts">
    Retrieve up to 100 Posts in a single request:

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/tweets?\
      ids=1228393702244134912,1227640996038684673,1199786642791452673&\
      tweet.fields=created_at,author_id" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Get multiple Posts by IDs
      response = client.posts.get_posts(
          ids=["1228393702244134912", "1227640996038684673", "1199786642791452673"],
          tweet_fields=["created_at", "author_id"]
      )

      for post in response.data:
          print(f"{post.id}: {post.text[:50]}...")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      const response = await client.posts.getPosts({
        ids: ["1228393702244134912", "1227640996038684673", "1199786642791452673"],
        tweetFields: ["created_at", "author_id"],
      });

      response.data?.forEach((post) => {
        console.log(`${post.id}: ${post.text?.slice(0, 50)}...`);
      });
      ```
    </CodeGroup>
  </Step>
</Steps>

***

## Next steps

<CardGroup>
  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/lookup/integrate">
    Learn authentication, rate limits, and best practices
  </Card>

  <Card title="Fields and expansions" icon="sliders" href="/x-api/fundamentals/fields">
    Master the fields and expansions system
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/get-post-by-id">
    See all available parameters
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Explore more examples
  </Card>
</CardGroup>


# Integration guide
Source: https://docs.x.com/x-api/posts/manage-tweets/integrate

This page covers tools and key concepts for integrating the manage Posts endpoints into. Reference for the X API v2 standard tier covering manage tweets.

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:

### 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.

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 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 OAuth 2.0 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 App's authentication settings found in the App settings section of the Developer Console.

### 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.

### 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.

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 200 requests per 15 minutes for the POST method. The DELETE method has a rate limit of 50 requests for 15 minutes. Additionally, there is a limit of [300 requests per 3 hours](https://blog.x.com/developer/en_us/topics/tools/2018/new-developer-requirements-to-protect-our-platform), including Posts created with either manage Posts or manage Retweets.

### Source labels

Your App name and website URL will be shown as the [source label](https://help.x.com/en/using-twitter/how-to-tweet#source-labels) within metadata for any Posts created programmatically by your application. If you change the use case of a X App, be sure to update the use case in these settings in order to ensure you are in compliance with the [Developer Terms](https://developer.x.com/content/developer-twitter/en/developer-terms/agreement-and-policy).

### Profile settings

You can only add a location to Posts if you have geo enabled in your profile settings. If you don't have geo enabled, you can still add a location parameter in your request body, but it won't get attached to your Post. The same is also true for tagging users in images. If the user you're tagging doesn't have photo-tagging enabled, their names won't show up in the list of tagged users even though the Post is successfully created.

### Adding media to a Post

Currently, isn't a way to fully upload media using v2 of the X API currently. However, you attach previously uploaded media to a Post. You can use media IDs that have been already [uploaded using the media upload endpoint](/x-api/media/upload-media) or [X Media Studio](https://media.x.com/en/articles/products/2018/media-studio). These media ids must be your own or that of an authenticated user.

***

## Code examples

### Create a Post

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.x.com/2/tweets" \
    -H "Authorization: OAuth ..." \
    -H "Content-Type: application/json" \
    -d '{"text": "Hello world!"}'
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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}`);
  ```
</CodeGroup>

### Create a reply

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.x.com/2/tweets" \
    -H "Authorization: OAuth ..." \
    -H "Content-Type: application/json" \
    -d '{"text": "This is a reply!", "reply": {"in_reply_to_tweet_id": "1234567890"}}'
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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 reply
  response = client.posts.create(
      text="This is a reply!",
      reply={"in_reply_to_tweet_id": "1234567890"}
  )
  print(f"Created reply: {response.data.id}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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 reply
  const response = await client.posts.create({
    text: "This is a reply!",
    reply: { inReplyToTweetId: "1234567890" },
  });
  console.log(`Created reply: ${response.data?.id}`);
  ```
</CodeGroup>

### Delete a Post

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.x.com/2/tweets/1234567890" \
    -H "Authorization: OAuth ..."
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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}`);
  ```
</CodeGroup>

**Next steps**

[API reference](/x-api/posts/manage-tweets#manage-tweets-api-reference-index)


# Manage Posts on the X API v2
Source: https://docs.x.com/x-api/posts/manage-tweets/introduction

Create and delete Posts on behalf of authenticated users with the X API v2 standard tier manage Posts endpoints, including request and response details.

The Manage Posts endpoints let you create and delete Posts on behalf of authenticated users. Build applications that post content, create threads, or manage user Posts.

## Overview

<CardGroup>
  <Card title="Create Post" icon="pen">
    Publish a new Post
  </Card>

  <Card title="Delete Post" icon="trash">
    Delete an existing Post
  </Card>

  <Card title="Reply" icon="reply">
    Reply to another Post
  </Card>

  <Card title="Quote" icon="quote-right">
    Quote another Post
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                    | Description       |
| :----- | :------------------------------------------ | :---------------- |
| POST   | [`/2/tweets`](/x-api/posts/create-post)     | Create a new Post |
| DELETE | [`/2/tweets/:id`](/x-api/posts/delete-post) | Delete a Post     |

***

## Creating Posts

### Basic Post

```bash theme={null}
curl -X POST "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from the API!"}'
```

<Note>
  **Self-serve customers:** Posts created via the API are limited to a maximum of 1 cashtag per post.
</Note>

### Reply to a Post

```bash theme={null}
curl -X POST "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is a reply!",
    "reply": {
      "in_reply_to_tweet_id": "1234567890"
    }
  }'
```

<Note>
  **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.
</Note>

### Quote a Post

```bash theme={null}
curl -X POST "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Check this out!",
    "quote_tweet_id": "1234567890"
  }'
```

### Post with media

```bash theme={null}
curl -X POST "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Photo of the day",
    "media": {
      "media_ids": ["1234567890123456789"]
    }
  }'
```

<Note>
  Upload media first using the [Media Upload endpoint](/x-api/media/quickstart/media-upload-chunked), then reference the `media_id` in your Post.
</Note>

### Post with poll

```bash theme={null}
curl -X POST "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "What is your favorite color?",
    "poll": {
      "options": ["Red", "Blue", "Green", "Yellow"],
      "duration_minutes": 1440
    }
  }'
```

### Post with paid partnership

Use the `paid_partnership` field when creating a Post to indicate it is a paid partnership (i.e., the author is disclosing that the Post contains paid promotion). When set to `true`, the Post will be labeled as a paid promotion.

```bash theme={null}
curl -X POST "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Excited to partner with Acme on their latest launch!",
    "paid_partnership": true
  }'
```

To retrieve the value on existing Posts (including your own), request it via the `tweet.fields` parameter:

```bash theme={null}
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=paid_partnership,created_at" \
  -H "Authorization: Bearer $TOKEN"
```

***

## Deleting Posts

```bash theme={null}
curl -X DELETE "https://api.x.com/2/tweets/1234567890" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
```

<Warning>
  You can only delete Posts authored by the authenticated user.
</Warning>

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * User Access Tokens via [OAuth 2.0 PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) or [3-legged OAuth](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/manage-tweets/quickstart">
    Create your first Post
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/manage-tweets/integrate">
    Key concepts and best practices
  </Card>

  <Card title="Media upload" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-photo.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=d0986097dcff55478c32801b20440ecc" href="/x-api/media/quickstart/media-upload-chunked">
    Upload media for Posts
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/creation-of-a-post">
    Full endpoint documentation
  </Card>
</CardGroup>


# Manage Posts endpoints migration overview
Source: https://docs.x.com/x-api/posts/manage-tweets/migrate/overview

Move Post creation and deletion from Standard v1.1 statuses endpoints to X API v2 by comparing parameters, authentication, and rate limits.

## Comparing X API’s manage Posts endpoints

The v2 manage Posts endpoints will replace 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. If you have code, apps, or tools that use the v1.1 version of the manage Posts 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 manage Posts endpoints:

### Create a Post

| Description                                                                                                                                                        | Standard v1.1                                                                                                  | X API v2                                                                                                                                 |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| HTTP methods supported                                                                                                                                             | POST                                                                                                           | POST                                                                                                                                     |
| Host domain                                                                                                                                                        | [https://api.x.com](https://api.x.com)                                                                         | [https://api.x.com](https://api.x.com)                                                                                                   |
| Endpoint path                                                                                                                                                      | /1.1/statuses/update.json                                                                                      | /2/tweets                                                                                                                                |
| [Authentication](/resources/fundamentals/authentication)                                                                                                           | OAuth 1.0a User Context                                                                                        | OAuth 1.0a User Context<br /><br />OAuth 2.0 Authorization Code with PKCE                                                                |
| Default request [rate limits](/x-api/fundamentals/rate-limits)                                                                                                     | None<br /><br />300 requests per 3-hour window per user, per app. Shared with the v1.1 POST Retweets endpoint. | 200 requests per 15 min per user<br /><br />300 requests per 3-hour window per user, per app. Shared with the v2 POST Retweets endpoint. |
| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) |                                                                                                                | ✔                                                                                                                                        |

### Delete a Post

| Description                                                                                                                                                        | Standard v1.1                          | X API v2                                                                  |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- | :------------------------------------------------------------------------ |
| HTTP methods supported                                                                                                                                             | POST                                   | DELETE                                                                    |
| Host domain                                                                                                                                                        | [https://api.x.com](https://api.x.com) | [https://api.x.com](https://api.x.com)                                    |
| Endpoint path                                                                                                                                                      | /1.1/statuses/destroy/:id.json         | /2/tweets/:id                                                             |
| [Authentication](/resources/fundamentals/authentication)                                                                                                           | OAuth 1.0a User Context                | OAuth 1.0a User Context<br /><br />OAuth 2.0 Authorization Code with PKCE |
| Default request [rate limits](/x-api/fundamentals/rate-limits)                                                                                                     | None                                   | 50 requests per 15 min per user                                           |
| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) |                                        | ✔                                                                         |

### Other migration resources

[Manage Posts: Standard v1.1 to X API v2](/x-api/posts/manage-tweets#standard-v1-1-compared-to-x-api-v2 "Manage Posts: Standard v1.1 to X API v2")

[X API migration hub](/x-api/migrate/overview)


# v1 to v2
Source: https://docs.x.com/x-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2

If you have been working with the standard v1.1 POST statuses/update and POST. Reference for the X API v2 standard tier covering migrate.

## 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.

* **Similarities**
  * Authentication
* **Differences**
  * Endpoint URLs

  * App and Project requirements

  * Request parameters

### Similarities

**Authentication**

Both the standard v1.1 and X API v2 manage Posts ([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 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 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:
  * [https://api.x.com/1.1/statuses/update.json](https://api.x.com/1.1/statuses/update.json)
    (Creates a Post)
  * `https://api.x.com/1.1/statuses/destroy/:id.json`
    (Deletes a Post)
* X API v2 endpoint:
  * [https://api.x.com/2/tweets](https://api.x.com/2/tweets)
    (Creates a Post)
  * [https://api.x.com/2/tweets/:id](https://api.x.com/2/tweets/:id)
    (Deletes a specified 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.


# X API v2 manage Posts quickstart
Source: https://docs.x.com/x-api/posts/manage-tweets/quickstart

Step-by-step quickstart for creating and deleting Posts with the X API v2 standard tier, including authentication, request payloads, and examples.

This guide walks you through creating and deleting Posts using the X API.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Tokens (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Create a Post

<Steps>
  <Step title="Prepare your request">
    The POST `/2/tweets` endpoint requires a JSON body with at least `text` or `media`:

    ```json theme={null}
    {
      "text": "Hello from the X API!"
    }
    ```
  </Step>

  <Step title="Send the request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/tweets" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"text": "Hello from the X API!"}'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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 from the X API!")
      print(f"Created Post: {response.data.id}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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 from the X API!" });
      console.log(`Created Post: ${response.data?.id}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    A successful response includes the new Post's `id` and `text`:

    ```json theme={null}
    {
      "data": {
        "id": "1445880548472328192",
        "text": "Hello from the X API!"
      }
    }
    ```
  </Step>
</Steps>

***

## Advanced examples

<AccordionGroup>
  <Accordion title="Reply to a Post">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/tweets" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "text": "This is a reply!",
          "reply": {
            "in_reply_to_tweet_id": "1234567890"
          }
        }'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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 reply
      response = client.posts.create(
          text="This is a reply!",
          reply={"in_reply_to_tweet_id": "1234567890"}
      )
      print(f"Created reply: {response.data.id}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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 reply
      const response = await client.posts.create({
        text: "This is a reply!",
        reply: { inReplyToTweetId: "1234567890" },
      });
      console.log(`Created reply: ${response.data?.id}`);
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Quote a Post">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/tweets" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "text": "Check this out!",
          "quote_tweet_id": "1234567890"
        }'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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)

      # Quote a Post
      response = client.posts.create(
          text="Check this out!",
          quote_tweet_id="1234567890"
      )
      print(f"Created quote: {response.data.id}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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 });

      // Quote a Post
      const response = await client.posts.create({
        text: "Check this out!",
        quoteTweetId: "1234567890",
      });
      console.log(`Created quote: ${response.data?.id}`);
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Post with media">
    First, upload media using the [Media Upload endpoint](/x-api/media/quickstart/media-upload-chunked), then reference the `media_id`:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/tweets" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "text": "Photo of the day!",
          "media": {
            "media_ids": ["1234567890123456789"]
          }
        }'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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)

      # Post with media
      response = client.posts.create(
          text="Photo of the day!",
          media={"media_ids": ["1234567890123456789"]}
      )
      print(f"Created Post with media: {response.data.id}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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 });

      // Post with media
      const response = await client.posts.create({
        text: "Photo of the day!",
        media: { mediaIds: ["1234567890123456789"] },
      });
      console.log(`Created Post with media: ${response.data?.id}`);
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Post with poll">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/tweets" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "text": "What is your favorite color?",
          "poll": {
            "options": ["Red", "Blue", "Green", "Yellow"],
            "duration_minutes": 1440
          }
        }'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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)

      # Post with poll
      response = client.posts.create(
          text="What is your favorite color?",
          poll={"options": ["Red", "Blue", "Green", "Yellow"], "duration_minutes": 1440}
      )
      print(f"Created poll: {response.data.id}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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 });

      // Post with poll
      const response = await client.posts.create({
        text: "What is your favorite color?",
        poll: { options: ["Red", "Blue", "Green", "Yellow"], durationMinutes: 1440 },
      });
      console.log(`Created poll: ${response.data?.id}`);
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Post with paid partnership">
    Use the `paid_partnership` field to indicate that this Post is a paid partnership (i.e., the author is disclosing it contains paid promotion). When set to `true`, the Post will be labeled as a paid promotion.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/tweets" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "text": "Excited to partner with Acme on their latest launch!",
          "paid_partnership": true
        }'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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)

      # Post with paid partnership
      response = client.posts.create(
          text="Excited to partner with Acme on their latest launch!",
          paid_partnership=True
      )
      print(f"Created paid partnership post: {response.data.id}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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 });

      // Post with paid partnership
      const response = await client.posts.create({
        text: "Excited to partner with Acme on their latest launch!",
        paidPartnership: true,
      });
      console.log(`Created paid partnership post: ${response.data?.id}`);
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

## Delete a Post

<Steps>
  <Step title="Get the Post ID">
    You need the ID of the Post you want to delete. This is returned when you create a Post.
  </Step>

  <Step title="Send a DELETE request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X DELETE "https://api.x.com/2/tweets/1445880548472328192" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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("1445880548472328192")
      print(f"Deleted: {response.data.deleted}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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("1445880548472328192");
      console.log(`Deleted: ${response.data?.deleted}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Confirm deletion">
    ```json theme={null}
    {
      "data": {
        "deleted": true
      }
    }
    ```
  </Step>
</Steps>

<Warning>
  You can only delete Posts that you authored.
</Warning>

***

## Next steps

<CardGroup>
  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/manage-tweets/integrate">
    Key concepts and best practices
  </Card>

  <Card title="Media upload" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-photo.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=d0986097dcff55478c32801b20440ecc" href="/x-api/media/quickstart/media-upload-chunked">
    Upload media for Posts
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/create-post">
    Full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# Quote Posts
Source: https://docs.x.com/x-api/posts/quote-tweets/introduction

The Quote Posts endpoint lets you retrieve Posts that quote a specific Post. Reference for the X API v2 standard tier covering quote tweets.

The Quote Posts endpoint lets you retrieve Posts that quote a specific Post. See how users are commenting on and sharing content.

## Overview

<CardGroup>
  <Card title="Quote lookup" icon="quote-right">
    Get all Quote Posts for a Post
  </Card>

  <Card title="Engagement insight" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bar-chart.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=e2a41caa858b122416f0005a55a8f143">
    See how content is being discussed
  </Card>
</CardGroup>

***

## Endpoint

| Method | Endpoint                                                      | Description                |
| :----- | :------------------------------------------------------------ | :------------------------- |
| GET    | [`/2/tweets/:id/quote_tweets`](/x-api/posts/get-quoted-posts) | Get Quote Posts for a Post |

***

## Example request

```bash theme={null}
curl "https://api.x.com/2/tweets/1234567890/quote_tweets?\
tweet.fields=created_at,author_id,public_metrics&\
expansions=author_id&\
user.fields=username" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

## Example response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "9876543210",
      "text": "Great point! This is exactly what we need.",
      "author_id": "1111111111",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "includes": {
    "users": [
      {
        "id": "1111111111",
        "username": "example_user"
      }
    ]
  },
  "meta": {
    "result_count": 1
  }
}
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/quote-tweets/quickstart">
    Get Quote Posts for a Post
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/get-quoted-posts">
    Full endpoint documentation
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.x.com/x-api/posts/quote-tweets/quickstart

This guide walks you through retrieving Quote Posts (Posts that quote another Post). Reference for the X API v2 standard tier covering quote tweets.

This guide walks you through retrieving Quote Posts (Posts that quote another Post).

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token
</Note>

***

<Steps>
  <Step title="Find the Post ID" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=9fde7d51b4f18c96d3a38a81d519761f">
    Get the ID of the Post you want to find quotes for. You can find it in the Post's URL:

    ```
    https://x.com/XDevelopers/status/1409931481552543749
                                    └── This is the Post ID
    ```
  </Step>

  <Step title="Request Quote Posts" icon="terminal">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/tweets/1409931481552543749/quote_tweets?\
      tweet.fields=created_at,public_metrics,author_id&\
      expansions=author_id&\
      user.fields=username,verified&\
      max_results=10" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Get Quote Posts with pagination
      for page in client.posts.get_quote_tweets(
          "1409931481552543749",
          tweet_fields=["created_at", "public_metrics", "author_id"],
          expansions=["author_id"],
          user_fields=["username", "verified"],
          max_results=10
      ):
          for post in page.data:
              print(f"{post.text[:50]}... - Likes: {post.public_metrics.like_count}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Get Quote Posts with pagination
      const paginator = client.posts.getQuoteTweets("1409931481552543749", {
        tweetFields: ["created_at", "public_metrics", "author_id"],
        expansions: ["author_id"],
        userFields: ["username", "verified"],
        maxResults: 10,
      });

      for await (const page of paginator) {
        page.data?.forEach((post) => {
          console.log(`${post.text?.slice(0, 50)}... - Likes: ${post.public_metrics?.like_count}`);
        });
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response" icon="eye">
    ```json theme={null}
    {
      "data": [
        {
          "id": "1495979553889697792",
          "text": "Great thread on the new API features! https://t.co/...",
          "author_id": "29757971",
          "created_at": "2022-02-22T04:31:34.000Z",
          "public_metrics": {
            "retweet_count": 5,
            "reply_count": 2,
            "like_count": 42,
            "quote_count": 1
          },
          "edit_history_tweet_ids": ["1495979553889697792"]
        }
      ],
      "includes": {
        "users": [
          {
            "id": "29757971",
            "username": "developer",
            "verified": false
          }
        ]
      },
      "meta": {
        "result_count": 1,
        "next_token": "avdjwk0udyx6"
      }
    }
    ```
  </Step>

  <Step title="Paginate through results" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e">
    The SDKs handle pagination automatically. For cURL, use the `next_token` to get more Quote Posts:

    ```bash theme={null}
    curl "https://api.x.com/2/tweets/1409931481552543749/quote_tweets?\
    max_results=10&\
    pagination_token=avdjwk0udyx6" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```
  </Step>
</Steps>

***

## Next steps

<CardGroup>
  <Card title="Retweets" icon="retweet" href="/x-api/posts/retweets/introduction">
    Look up Retweets
  </Card>

  <Card title="Post lookup" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/lookup/introduction">
    Look up Posts by ID
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/get-quoted-posts">
    Full endpoint documentation
  </Card>
</CardGroup>


# Integration guide
Source: https://docs.x.com/x-api/posts/retweets/integrate

This page covers tools and key concepts for integrating the Retweet endpoints. Reference for the X API v2 standard tier covering retweets.

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/reference#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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/tweets/1234567890/retweeted_by?user.fields=username,verified" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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}`);
  });
  ```
</CodeGroup>

#### Retweet a Post

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.x.com/2/users/123/retweets" \
    -H "Authorization: OAuth ..." \
    -H "Content-Type: application/json" \
    -d '{"tweet_id": "1234567890"}'
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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);
  ```
</CodeGroup>


# Retweets
Source: https://docs.x.com/x-api/posts/retweets/introduction

The Retweets endpoints let you retweet and undo retweets, see who retweeted a Post, and get. Reference for the X API v2 standard tier covering retweets.

The Retweets endpoints let you retweet and undo retweets, see who retweeted a Post, and get reposts of your own Posts.

## Overview

<CardGroup>
  <Card title="Retweet" icon="retweet">
    Retweet a Post on behalf of a user
  </Card>

  <Card title="Undo retweet" icon="xmark">
    Remove a retweet
  </Card>

  <Card title="Retweeting users" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980">
    See who retweeted a Post
  </Card>

  <Card title="Reposts of me" icon="repeat">
    Get reposts of your own Posts
  </Card>
</CardGroup>

***

## Endpoints

### Retweets lookup

| Method | Endpoint                                                      | Description                               |
| :----- | :------------------------------------------------------------ | :---------------------------------------- |
| GET    | [`/2/tweets/:id/retweeted_by`](/x-api/posts/get-reposted-by)  | Get users who retweeted a Post            |
| GET    | [`/2/tweets/:id/quote_tweets`](/x-api/posts/get-quoted-posts) | Get quote Posts of a Post                 |
| GET    | [`/2/users/reposts_of_me`](/x-api/users/get-reposts-of-me)    | Get reposts of authenticated user's Posts |

### Manage retweets

| Method | Endpoint                                                        | Description    |
| :----- | :-------------------------------------------------------------- | :------------- |
| POST   | [`/2/users/:id/retweets`](/x-api/users/repost-post)             | Retweet a Post |
| DELETE | [`/2/users/:id/retweets/:tweet_id`](/x-api/users/unrepost-post) | Undo a retweet |

***

## Example: Get retweeting users

```bash theme={null}
curl "https://api.x.com/2/tweets/1234567890/retweeted_by?\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

## Example: Retweet a Post

```bash theme={null}
curl -X POST "https://api.x.com/2/users/123456789/retweets" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tweet_id": "1234567890"}'
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Lookup quickstart" icon="retweet" href="/x-api/posts/retweets/quickstart/retweets-lookup">
    Get retweets for a Post
  </Card>

  <Card title="Manage quickstart" icon="plus" href="/x-api/posts/retweets/quickstart/manage-retweets">
    Retweet and undo retweets
  </Card>

  <Card title="Reposts of me" icon="repeat" href="/x-api/posts/retweets/quickstart/retweets-of-me">
    Get reposts of your Posts
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/get-reposted-by">
    Full endpoint documentation
  </Card>
</CardGroup>


# Manage Retweets
Source: https://docs.x.com/x-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2

If you have been working with the standard v1.1 POST statuses/retweet/:id, and POST. Reference for the X API v2 standard tier covering migrate.

### 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](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](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:


# Reposts endpoints migration overview
Source: https://docs.x.com/x-api/posts/retweets/migrate/overview

Migrate Repost (retweet) lookup, creation, and deletion from Standard v1.1 to X API v2 with side-by-side endpoint, parameter, and limit comparisons.

## 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)                      | [https://api.x.com](https://api.x.com)                                                                                                                                                                                                                                                                                                                |
| Endpoint path                                                                                                                                                              | /1.1/retweeters/id.json<br /><br />`/1.1/retweets/ids.json` | /2/users/:id/retweeted\_by                                                                                                                                                                                                                                                                                                                            |
| [Authentication](/resources/fundamentals/authentication)                                                                                                                   | OAuth 1.0a User Context                                     | OAuth 2.0 Bearer Token<br /><br />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)<br /><br />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)<br /><br />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)                                                                          | [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<br /><br />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)<br /><br />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) | [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)


# Retweets lookup
Source: https://docs.x.com/x-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2

If you have been working with the standard v1.1 v1.1 GET statuses/retweets/:id, v1.1 GET. Reference for the X API v2 standard tier covering migrate.

### 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**
  * Authentication
  * 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](https://api.x.com/1.1/statuses/retweets/:id.json)
    (Returns a collection of the 100 most recent


# Manage Retweets
Source: https://docs.x.com/x-api/posts/retweets/quickstart/manage-retweets

This guide walks you through Retweeting and undoing Retweets using the X API. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through Retweeting and undoing Retweets using the X API.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Retweet a Post

<Steps>
  <Step title="Get your user ID">
    You need your authenticated user's ID. You can find it using the [user lookup endpoint](/x-api/users/lookup/introduction) or from your Access Token (the numeric part is your user ID).
  </Step>

  <Step title="Get the Post ID">
    Find the Post ID in the URL when viewing a Post:

    ```
    https://x.com/XDevelopers/status/1228393702244134912
                                    └── This is the Post ID
    ```
  </Step>

  <Step title="Send the Retweet request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/users/123456789/retweets" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"tweet_id": "1228393702244134912"}'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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="1228393702244134912"
      )

      print(f"Retweeted: {response.data.retweeted}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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: "1228393702244134912",
      });

      console.log(`Retweeted: ${response.data?.retweeted}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": {
        "retweeted": true
      }
    }
    ```
  </Step>
</Steps>

***

## Undo a Retweet

Remove a Retweet:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.x.com/2/users/123456789/retweets/1228393702244134912" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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="1228393702244134912"
  )

  print(f"Retweeted: {response.data.retweeted}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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", "1228393702244134912");

  console.log(`Retweeted: ${response.data?.retweeted}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "retweeted": false
  }
}
```

***

## Next steps

<CardGroup>
  <Card title="Retweets lookup" icon="retweet" href="/x-api/posts/retweets/quickstart/retweets-lookup">
    Get users who Retweeted a Post
  </Card>

  <Card title="Quote Posts" icon="quote-left" href="/x-api/posts/quote-tweets/quickstart">
    Get Quote Posts
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/repost-post">
    Full endpoint documentation
  </Card>
</CardGroup>


# Retweets Lookup
Source: https://docs.x.com/x-api/posts/retweets/quickstart/retweets-lookup

This guide walks you through retrieving users who Retweeted a specific Post. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through retrieving users who Retweeted a specific Post.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token (for public data) or User Access Token (for private metrics)
</Note>

***

## Get users who Retweeted a Post

<Steps>
  <Step title="Find the Post ID">
    Get the ID of the Post you want to look up Retweets for:

    ```
    https://x.com/XDevelopers/status/1354143047324299264
                                    └── This is the Post ID
    ```
  </Step>

  <Step title="Make the request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/tweets/1354143047324299264/retweeted_by?\
      user.fields=created_at,username,verified" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python Python SDK theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Get users who Retweeted a Post with pagination
      for page in client.posts.get_retweeted_by(
          "1354143047324299264",
          user_fields=["created_at", "username", "verified"]
      ):
          for user in page.data:
              print(f"{user.username} - Joined: {user.created_at}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Get users who Retweeted a Post with pagination
      const paginator = client.posts.getRetweetedBy("1354143047324299264", {
        userFields: ["created_at", "username", "verified"],
      });

      for await (const page of paginator) {
        page.data?.forEach((user) => {
          console.log(`${user.username} - Joined: ${user.created_at}`);
        });
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": [
        {
          "created_at": "2008-12-04T18:51:57.000Z",
          "id": "17874544",
          "username": "TwitterSupport",
          "name": "Twitter Support",
          "verified": true
        },
        {
          "created_at": "2007-02-20T14:35:54.000Z",
          "id": "783214",
          "username": "Twitter",
          "name": "Twitter",
          "verified": true
        }
      ],
      "meta": {
        "result_count": 2,
        "next_token": "7140dibdnow9c7btw3z2vwioavpvutgzrzm9icis4ndix"
      }
    }
    ```
  </Step>
</Steps>

***

## Include additional data

Use expansions to get related data like pinned Posts:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/tweets/1354143047324299264/retweeted_by?\
  user.fields=created_at&\
  expansions=pinned_tweet_id&\
  tweet.fields=created_at" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get Retweeting users with expansions
  for page in client.posts.get_retweeted_by(
      "1354143047324299264",
      user_fields=["created_at"],
      expansions=["pinned_tweet_id"],
      tweet_fields=["created_at"]
  ):
      for user in page.data:
          print(f"{user.username}")
      # Pinned Posts are in page.includes.tweets
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get Retweeting users with expansions
  const paginator = client.posts.getRetweetedBy("1354143047324299264", {
    userFields: ["created_at"],
    expansions: ["pinned_tweet_id"],
    tweetFields: ["created_at"],
  });

  for await (const page of paginator) {
    page.data?.forEach((user) => {
      console.log(user.username);
    });
    // Pinned Posts are in page.includes?.tweets
  }
  ```
</CodeGroup>

### Response with expansion

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "pinned_tweet_id": "1389270063807598594",
      "created_at": "2018-11-21T14:24:58.000Z",
      "id": "1065249714214457345",
      "username": "TwitterSpaces",
      "name": "Spaces"
    }
  ],
  "includes": {
    "tweets": [
      {
        "created_at": "2021-05-03T17:26:09.000Z",
        "id": "1389270063807598594",
        "text": "now, everyone with 600 or more followers can host a Space..."
      }
    ]
  }
}
```

***

## Next steps

<CardGroup>
  <Card title="Manage Retweets" icon="retweet" href="/x-api/posts/retweets/quickstart/manage-retweets">
    Retweet and undo Retweets
  </Card>

  <Card title="Quote Posts" icon="quote-left" href="/x-api/posts/quote-tweets/quickstart">
    Get Quote Posts
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/get-reposted-by">
    Full endpoint documentation
  </Card>
</CardGroup>


# Retweets of Me
Source: https://docs.x.com/x-api/posts/retweets/quickstart/retweets-of-me

This guide walks you through retrieving your Posts that have been Retweeted by others. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through retrieving your Posts that have been Retweeted by others.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Why use Retweets of Me?

The Retweets of Me endpoint helps you:

* **Track engagement** — See which of your Posts are being shared
* **Understand resonance** — Learn what content resonates with your audience
* **Inform strategy** — Adjust your content strategy based on sharing patterns

***

## Get your Retweeted Posts

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/reposts_of_me?\
  tweet.fields=created_at,public_metrics&\
  max_results=10" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get your Posts that have been Retweeted
  for page in client.posts.get_reposts_of_me(
      tweet_fields=["created_at", "public_metrics"],
      max_results=10
  ):
      for post in page.data:
          print(f"{post.text[:50]}... - Retweets: {post.public_metrics.retweet_count}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get your Posts that have been Retweeted
  const paginator = client.posts.getRepostsOfMe({
    tweetFields: ["created_at", "public_metrics"],
    maxResults: 10,
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(`${post.text?.slice(0, 50)}... - Retweets: ${post.public_metrics?.retweet_count}`);
    });
  }
  ```
</CodeGroup>

***

## Response

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "1848781937210802364",
      "text": "ever wanted to discover trends.. before they're trends?...",
      "created_at": "2024-01-15T10:30:00.000Z",
      "public_metrics": {
        "retweet_count": 42,
        "reply_count": 5,
        "like_count": 156,
        "quote_count": 8
      },
      "edit_history_tweet_ids": ["1848781937210802364"]
    },
    {
      "id": "1847990559081648620",
      "text": "posting is just journaling with an audience",
      "created_at": "2024-01-14T15:20:00.000Z",
      "public_metrics": {
        "retweet_count": 28,
        "reply_count": 12,
        "like_count": 89,
        "quote_count": 3
      },
      "edit_history_tweet_ids": ["1847990559081648620"]
    }
  ],
  "meta": {
    "result_count": 2,
    "next_token": "7140dibdnow9c7btw481s8m561gat797rboud5r80xvzm"
  }
}
```

***

## Filter by time range

Get Retweeted Posts from a specific period:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/reposts_of_me?\
  start_time=2024-01-01T00%3A00%3A00Z&\
  end_time=2024-01-31T23%3A59%3A59Z&\
  tweet.fields=created_at,public_metrics" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get Retweeted Posts from a time range
  for page in client.posts.get_reposts_of_me(
      start_time="2024-01-01T00:00:00Z",
      end_time="2024-01-31T23:59:59Z",
      tweet_fields=["created_at", "public_metrics"]
  ):
      for post in page.data:
          print(f"{post.created_at}: {post.text[:50]}...")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get Retweeted Posts from a time range
  const paginator = client.posts.getRepostsOfMe({
    startTime: "2024-01-01T00:00:00Z",
    endTime: "2024-01-31T23:59:59Z",
    tweetFields: ["created_at", "public_metrics"],
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(`${post.created_at}: ${post.text?.slice(0, 50)}...`);
    });
  }
  ```
</CodeGroup>

***

## Common parameters

| Parameter          | Description                      | Default      |
| :----------------- | :------------------------------- | :----------- |
| `max_results`      | Results per page (1-100)         | 10           |
| `start_time`       | Oldest Post timestamp (ISO 8601) | —            |
| `end_time`         | Newest Post timestamp (ISO 8601) | —            |
| `pagination_token` | Token for next page              | —            |
| `tweet.fields`     | Additional Post fields           | `id`, `text` |

***

## Next steps

<CardGroup>
  <Card title="Retweets lookup" icon="retweet" href="/x-api/posts/retweets/quickstart/retweets-lookup">
    See who Retweeted a Post
  </Card>

  <Card title="Manage Retweets" icon="share" href="/x-api/posts/retweets/quickstart/manage-retweets">
    Retweet and undo Retweets
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-reposts-of-me">
    Full endpoint documentation
  </Card>
</CardGroup>


# Search Posts All
Source: https://docs.x.com/x-api/posts/search-all-posts

get /2/tweets/search/all
At most one of `start_time`, `since_id` may be provided. At most one of `end_time`, `until_id` may be provided. At most one of `pagination_token`, `next_token` may be provided.



# Search Posts All
Source: https://docs.x.com/x-api/posts/search-posts-all

get /2/tweets/search/all
At most one of `start_time`, `since_id` may be provided. At most one of `end_time`, `until_id` may be provided. At most one of `pagination_token`, `next_token` may be provided.



# Search Posts Recent
Source: https://docs.x.com/x-api/posts/search-posts-recent

get /2/tweets/search/recent
At most one of `start_time`, `since_id` may be provided. At most one of `end_time`, `until_id` may be provided. At most one of `pagination_token`, `next_token` may be provided.



# Search Posts Recent
Source: https://docs.x.com/x-api/posts/search-recent-posts

get /2/tweets/search/recent
At most one of `start_time`, `since_id` may be provided. At most one of `end_time`, `until_id` may be provided. At most one of `pagination_token`, `next_token` may be provided.



# Build a query
Source: https://docs.x.com/x-api/posts/search/integrate/build-a-query

The search endpoints accept a single query with a GET request and return a set of historical. Reference for the X API v2 standard tier covering integrate.

The search endpoints accept a single query with a GET request and return a set of historical Posts that match the query. Queries are made up of operators that match on a variety of Post attributes.

***

## Query limitations

Your queries will be limited depending on which [access level](/x-api/getting-started/about-x-api) you are using:

| Access level | Recent search    | Full-archive search |
| :----------- | :--------------- | :------------------ |
| Self-serve   | 512 characters   | 1,024 characters    |
| Enterprise   | 4,096 characters | 4,096 characters    |

***

## Operator availability

While most operators are available to any developer, some are reserved for certain access levels:

* **Core operators:** Available when using any [Project](/resources/fundamentals/developer-apps)
* **Advanced operators:** Available when using a Project with certain access levels

See the complete [list of operators](/x-api/posts/search/integrate/operators) for availability details.

***

## 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, this query works because `#hashtag` is a standalone operator:

```
#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. This is because using these operators alone would match 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 a standalone operator, such as the phrase `"X data"`, the query works properly:

```
"X data" has:mentions (has:media OR has:links)
```

***

## Boolean operators and grouping

String together multiple operators using these tools:

| Operator                   | Description                           | Example                                                                 |
| :------------------------- | :------------------------------------ | :---------------------------------------------------------------------- |
| **AND** (space)            | Posts must match both conditions      | `snow day #NoSchool` matches Posts with "snow" AND "day" AND #NoSchool  |
| **OR**                     | Posts must match either condition     | `grumpy OR cat OR #meme` matches Posts with "grumpy" OR "cat" OR #meme  |
| **NOT** (dash)             | Exclude Posts matching this condition | `cat #meme -grumpy` matches Posts with "cat" and #meme but NOT "grumpy" |
| **Grouping** (parentheses) | Group operators together              | `(grumpy cat) OR (#meme has:images)` matches either group               |

<Note>
  **A note on negations**

  * The operator `-is:nullcast` must always be negated
  * Negated operators cannot be used alone
  * Do not negate grouped operators. Instead of `skiing -(snow OR day OR noschool)`, use `skiing -snow -day -noschool`
</Note>

***

## Order of operations

When combining AND and OR:

1. Operators connected by AND logic are combined first
2. Then, operators connected with OR logic are applied

**Examples:**

| Query                    | Evaluated as               |
| :----------------------- | :------------------------- |
| `apple OR iphone ipad`   | `apple OR (iphone ipad)`   |
| `ipad iphone OR android` | `(iphone ipad) OR android` |

To eliminate uncertainty, use parentheses:

```
(apple OR iphone) ipad
```

```
iphone (ipad OR android)
```

***

## Punctuation, diacritics, and case sensitivity

**Diacritics:** Search queries with accents or diacritics match Posts both with and without the accents. For example, `Diacrítica` matches both *Diacrítica* and *Diacritica*.

**Case sensitivity:** All operators are case-insensitive. The query `cat` matches *cat*, *CAT*, and *Cat*.

<Note>
  **Filtered stream behaves differently**

  When [building filtered stream rules](/x-api/posts/filtered-stream/integrate/build-a-rule), keywords with accents only match Posts that also include the accent. For example, `Diacrítica` only matches *Diacrítica*, not *Diacritica*.
</Note>

***

## Quote Tweet matching

When using Search Posts, operators match on the Quote Tweet's content but **not** on the content from the original Post that was quoted.

<Note>
  [Filtered stream](/x-api/posts/filtered-stream/introduction) behaves differently—it matches on both the Quote Tweet and the original Post's content.
</Note>

***

## Specificity and efficiency

<Warning>
  Using broad operators like a single keyword or hashtag is not recommended—it will match a massive volume of Posts and quickly consume your usage limits.
</Warning>

**Tips for building effective queries:**

1. **Start specific, then broaden** — Create targeted queries that return relevant results
2. **Use multiple operators** — Combine operators to narrow results
3. **Watch your character count** — The entire query string counts toward the limit

**Example progression:**

```
# Too broad - 200,000+ Posts per day
happy

# Better - adds language filter and exclusions
(happy OR happiness) lang:en -birthday -is:retweet

# Even better - 59 characters, more specific
(happy OR happiness) place_country:GB -birthday -is:retweet
```

***

## Iteratively building a query

### Step 1: Start with a basic query

```
happy OR happiness
```

### Step 2: Test and narrow based on results

We noticed Posts in many languages. Add a language filter:

```
(happy OR happiness) lang:en
```

We're getting birthday wishes. Exclude them and Retweets:

```
(happy OR happiness) lang:en -birthday -is:retweet
```

### Step 3: Broaden for better coverage

We want to capture more sentiment. Add related keywords:

```
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet
```

### Step 4: Adjust for trends

Holiday Posts are appearing. Exclude them:

```
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays
```

***

## Adding a query to your request

Use the `query` parameter and HTTP encode your query:

```bash theme={null}
curl "https://api.x.com/2/tweets/search/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

Match Posts from weather agencies about Hurricane Harvey:

**Query:**

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

**Full request URL:**

```
https://api.x.com/2/tweets/search/recent?query=has%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)%20-is%3Aretweet
```

### Sentiment analysis for #nowplaying

**Positive sentiment:**

```
#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
```

**Negative sentiment:**

```
#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
```

### Using Post annotations

Find Japanese Posts about pets (not cats) with images using the `context:` operator:

First, use [Post lookup](/x-api/posts/lookup/introduction) with `tweet.fields=context_annotations` to identify domain.entity IDs:

* Cats: `domain` 66, `entity` 852262932607926273
* Pets: `domain` 65, `entity` 852262932607926273

**Query:**

```
context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja
```

***

## Tools

<Card title="Query Builder Tool" icon="wrench" href="https://developer.x.com/apitools/query?query=">
  Build and test your queries interactively
</Card>

***

## Next steps

<CardGroup>
  <Card title="Operators reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/posts/search/integrate/operators">
    Complete list of available operators
  </Card>

  <Card title="Search quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/search/quickstart/recent-search">
    Make your first search request
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/search/integrate/overview">
    Full integration documentation
  </Card>
</CardGroup>


# Search Operators
Source: https://docs.x.com/x-api/posts/search/integrate/operators

This page provides a complete list of operators available when building a query for the Search. Reference for the X API v2 standard tier covering integrate.

This page provides a complete list of operators available when [building a query](/x-api/posts/search/integrate/build-a-query) for the Search API endpoints.

## Overview

Operators are used to match on specific Post attributes. There are two types:

* **Standalone operators** — Can be used alone or with any other operators
* **Conjunction-required operators** — Must be used with at least one standalone operator

***

## Keyword and phrase operators

| Operator         | Type       | Summary                                                  | Example                             |
| :--------------- | :--------- | :------------------------------------------------------- | :---------------------------------- |
| `keyword`        | Standalone | Matches a keyword within the Post body (tokenized match) | `pepsi OR cola OR "coca cola"`      |
| `emoji`          | Standalone | Matches an emoji within the Post body                    | `(😃 OR 😡) 😬`                     |
| `"exact phrase"` | Standalone | Matches the exact phrase within the Post body            | `("X API" OR #v2) -"recent search"` |

***

## Entity operators

| Operator | Type       | Summary                                          | Example                      |
| :------- | :--------- | :----------------------------------------------- | :--------------------------- |
| `#`      | Standalone | Matches Posts containing a hashtag (exact match) | `#thankunext #fanart`        |
| `@`      | Standalone | Matches Posts mentioning a username              | `(@XDevelopers OR @API) -@X` |
| `$`      | Standalone | Matches Posts containing a cashtag               | `$twtr OR @XDevelopers -$fb` |

***

## User operators

| Operator       | Type       | Summary                                   | Example                        |
| :------------- | :--------- | :---------------------------------------- | :----------------------------- |
| `from:`        | Standalone | Matches Posts from a specific user        | `from:XDevelopers OR from:API` |
| `to:`          | Standalone | Matches Posts in reply to a specific user | `to:XDevelopers OR to:API`     |
| `retweets_of:` | Standalone | Matches Retweets of a specific user       | `retweets_of:twitterdev`       |

***

## URL operators

| Operator | Type       | Summary                                                         | Example                               |
| :------- | :--------- | :-------------------------------------------------------------- | :------------------------------------ |
| `url:`   | Standalone | Tokenized match on URL (matches `url` or `expanded_url` fields) | `url:"https://developer.twitter.com"` |

***

## Context and entity operators

| Operator           | Type       | Summary                                                                | Example                               |
| :----------------- | :--------- | :--------------------------------------------------------------------- | :------------------------------------ |
| `context:`         | Standalone | Matches Posts with a specific domain/entity pair                       | `context:10.799022225751871488`       |
| `entity:`          | Standalone | Matches Posts with a specific entity string value (recent search only) | `entity:"Michael Jordan"`             |
| `conversation_id:` | Standalone | Matches Posts in a conversation thread                                 | `conversation_id:1334987486343299072` |

***

## List operator

| Operator | Type       | Summary                                       | Example    |
| :------- | :--------- | :-------------------------------------------- | :--------- |
| `list:`  | Standalone | Matches Posts from members of a specific List | `list:123` |

***

## Post reference operators

| Operator                | Type       | Summary                                 | Example                                    |
| :---------------------- | :--------- | :-------------------------------------- | :----------------------------------------- |
| `in_reply_to_tweet_id:` | Standalone | Matches replies to a specific Post      | `in_reply_to_tweet_id:1539382664746020864` |
| `retweets_of_tweet_id:` | Standalone | Matches Retweets of a specific Post     | `retweets_of_tweet_id:1539382664746020864` |
| `quotes_of_tweet_id:`   | Standalone | Matches Quote Tweets of a specific Post | `quotes_of_tweet_id:1539382664746020864`   |

***

## Location operators

| Operator         | Type       | Summary                                  | Example                                                     |
| :--------------- | :--------- | :--------------------------------------- | :---------------------------------------------------------- |
| `place:`         | Standalone | Matches Posts tagged with a location     | `place:"new york city" OR place:seattle`                    |
| `place_country:` | Standalone | Matches Posts with a country code        | `place_country:US OR place_country:MX`                      |
| `point_radius:`  | Standalone | Matches Posts within a radius of a point | `point_radius:[2.355128 48.861118 16km]`                    |
| `bounding_box:`  | Standalone | Matches Posts within a bounding box      | `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]` |

***

## Post type operators

| Operator       | Type                 | Summary                                      | Example                         |
| :------------- | :------------------- | :------------------------------------------- | :------------------------------ |
| `is:retweet`   | Conjunction required | Matches Retweets                             | `data @XDevelopers -is:retweet` |
| `is:reply`     | Conjunction required | Matches replies                              | `from:XDevelopers is:reply`     |
| `is:quote`     | Conjunction required | Matches Quote Tweets                         | `"sentiment analysis" is:quote` |
| `is:verified`  | Conjunction required | Matches Posts from verified authors          | `#nowplaying is:verified`       |
| `-is:nullcast` | Conjunction required | Excludes promotional Posts (must be negated) | `"mobile games" -is:nullcast`   |

***

## Content type operators

| Operator         | Type                 | Summary                                      | Example                              |
| :--------------- | :------------------- | :------------------------------------------- | :----------------------------------- |
| `has:hashtags`   | Conjunction required | Matches Posts with hashtags                  | `from:XDevelopers -has:hashtags`     |
| `has:cashtags`   | Conjunction required | Matches Posts with cashtags                  | `#stonks has:cashtags`               |
| `has:links`      | Conjunction required | Matches Posts with links                     | `from:XDevelopers has:links`         |
| `has:mentions`   | Conjunction required | Matches Posts with mentions                  | `#nowplaying has:mentions`           |
| `has:media`      | Conjunction required | Matches Posts with media (photo, GIF, video) | `(kittens OR puppies) has:media`     |
| `has:images`     | Conjunction required | Matches Posts with images                    | `#meme has:images`                   |
| `has:video_link` | Conjunction required | Matches Posts with native X videos           | `#icebucketchallenge has:video_link` |
| `has:geo`        | Conjunction required | Matches Posts with geolocation data          | `recommend #paris has:geo`           |

***

## Engagement operators

| Operator       | Type       | Summary                                                     | Example                           |
| :------------- | :--------- | :---------------------------------------------------------- | :-------------------------------- |
| `min_likes:`   | Standalone | Matches Posts with at least the specified number of Likes   | `#SuperBowl min_likes:100`        |
| `min_replies:` | Standalone | Matches Posts with at least the specified number of replies | `from:XDevelopers min_replies:10` |
| `min_reposts:` | Standalone | Matches Posts with at least the specified number of Reposts | `"breaking news" min_reposts:50`  |

Each operator takes a non-negative integer value and is available with both recent search and full-archive search.

<Warning>
  The equivalent operators on X web search are named `min_faves:` and `min_retweets:`. Those names are **not** valid in the X API and will be rejected with a 400 error. Use `min_likes:` and `min_reposts:` instead.
</Warning>

***

## Language operator

| Operator | Type                 | Summary                                         | Example                    |
| :------- | :------------------- | :---------------------------------------------- | :------------------------- |
| `lang:`  | Conjunction required | Matches Posts classified as a specific language | `recommend #paris lang:en` |

***

## Logical operators

| Operator    | Summary                          | Example                    |
| :---------- | :------------------------------- | :------------------------- |
| `OR`        | Logical OR between expressions   | `cat OR dog`               |
| Space (AND) | Logical AND between expressions  | `cat dog` (both required)  |
| `()`        | Grouping for complex expressions | `(cat OR dog) -is:retweet` |
| `-`         | Negation/exclusion               | `cat -grumpy`              |

***

## Supported languages

The `lang:` operator supports these BCP 47 language codes:

| Language  | Code | Language   | Code | Language            | Code    |
| :-------- | :--- | :--------- | :--- | :------------------ | :------ |
| Amharic   | `am` | Greek      | `el` | Portuguese          | `pt`    |
| Arabic    | `ar` | Gujarati   | `gu` | Romanian            | `ro`    |
| Armenian  | `hy` | Hebrew     | `iw` | Russian             | `ru`    |
| Basque    | `eu` | Hindi      | `hi` | Serbian             | `sr`    |
| Bengali   | `bn` | Hungarian  | `hu` | Simplified Chinese  | `zh-CN` |
| Bulgarian | `bg` | Indonesian | `in` | Slovak              | `sk`    |
| Catalan   | `ca` | Italian    | `it` | Slovenian           | `sl`    |
| Croatian  | `hr` | Japanese   | `ja` | Spanish             | `es`    |
| Czech     | `cs` | Kannada    | `kn` | Swedish             | `sv`    |
| Danish    | `da` | Korean     | `ko` | Tamil               | `ta`    |
| Dutch     | `nl` | Latvian    | `lv` | Telugu              | `te`    |
| English   | `en` | Lithuanian | `lt` | Thai                | `th`    |
| Estonian  | `et` | Malayalam  | `ml` | Traditional Chinese | `zh-TW` |
| Finnish   | `fi` | Marathi    | `mr` | Turkish             | `tr`    |
| French    | `fr` | Norwegian  | `no` | Ukrainian           | `uk`    |
| German    | `de` | Persian    | `fa` | Urdu                | `ur`    |
| Georgian  | `ka` | Polish     | `pl` | Vietnamese          | `vi`    |

***

## Query limitations

| Access level | Recent search    | Full-archive search |
| :----------- | :--------------- | :------------------ |
| Self-serve   | 512 characters   | 1,024 characters    |
| Enterprise   | 4,096 characters | 4,096 characters    |

***

## Next steps

<CardGroup>
  <Card title="Build a query" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e" href="/x-api/posts/search/integrate/build-a-query">
    Learn query syntax and best practices
  </Card>

  <Card title="Search introduction" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/search/introduction">
    Get started with Search
  </Card>

  <Card title="Query Builder Tool" icon="wrench" href="https://developer.x.com/apitools/query?query=">
    Build and test queries interactively
  </Card>
</CardGroup>


# Integration Guide
Source: https://docs.x.com/x-api/posts/search/integrate/overview

This guide covers the key concepts you need to integrate the Search Posts endpoints into your. Reference for the X API v2 standard tier covering integrate.

This guide covers the key concepts you need to integrate the Search Posts endpoints into your application.

***

## Authentication

### Recent search

Recent search supports multiple authentication methods:

| Method                                                                                                                         | Use case         |
| :----------------------------------------------------------------------------------------------------------------------------- | :--------------- |
| [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0)                                                         | Public Post data |
| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | Private metrics  |
| [OAuth 1.0a User Context](/resources/fundamentals/authentication)                                                              | Private metrics  |

### Full-archive search

Full-archive search only supports [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0) authentication.

<Warning>
  Private metrics (`non_public_metrics`, `organic_metrics`, `promoted_metrics`) are not available with full-archive search because it only supports App-Only authentication.
</Warning>

***

## Building queries

Queries use operators to match Posts. Combine operators with boolean logic:

```
(AI OR "machine learning") lang:en -is:retweet has:links
```

### Query length limits

| Access level | Recent search | Full-archive search |
| :----------- | :------------ | :------------------ |
| Self-serve   | 512 chars     | 1,024 chars         |
| Enterprise   | 4,096 chars   | 4,096 chars         |

### Operator types

| Type                     | Description                             | Example                   |
| :----------------------- | :-------------------------------------- | :------------------------ |
| **Standalone**           | Can be used alone                       | `#python`, `from:user`    |
| **Conjunction-required** | Must be used with a standalone operator | `has:media`, `is:retweet` |

<Card title="Build a query" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/search/integrate/build-a-query">
  Learn query syntax in detail
</Card>

<Card title="Operator reference" icon="list-check" href="/x-api/posts/search/integrate/operators">
  See all available operators
</Card>

***

## Fields and expansions

By default, the response includes only `id`, `text`, and `edit_history_tweet_ids`. Use parameters to request additional data.

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/tweets/search/recent?\
  query=python&\
  tweet.fields=created_at,public_metrics,author_id&\
  expansions=author_id,attachments.media_keys&\
  user.fields=username,verified&\
  media.fields=url,type" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Search recent Posts
  for page in client.posts.search_recent(
      query="python",
      tweet_fields=["created_at", "public_metrics", "author_id"],
      expansions=["author_id", "attachments.media_keys"],
      user_fields=["username", "verified"],
      media_fields=["url", "type"],
      max_results=100
  ):
      for post in page.data:
          print(f"{post.text} - Likes: {post.public_metrics.like_count}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Search recent Posts
  const paginator = client.posts.searchRecent("python", {
    tweetFields: ["created_at", "public_metrics", "author_id"],
    expansions: ["author_id", "attachments.media_keys"],
    userFields: ["username", "verified"],
    mediaFields: ["url", "type"],
    maxResults: 100,
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(`${post.text} - Likes: ${post.public_metrics?.like_count}`);
    });
  }
  ```
</CodeGroup>

### Available expansions

| Expansion                    | Returns                    |
| :--------------------------- | :------------------------- |
| `author_id`                  | Author's user object       |
| `attachments.media_keys`     | Attached media objects     |
| `attachments.poll_ids`       | Attached poll objects      |
| `referenced_tweets.id`       | Quoted or replied-to Posts |
| `geo.place_id`               | Place objects              |
| `entities.mentions.username` | Mentioned user objects     |

<Card title="Fields and expansions guide" icon="sliders" href="/x-api/fundamentals/fields">
  Learn more about customizing responses
</Card>

***

## Pagination

Search endpoints return results in pages. Use the `next_token` from the response to fetch additional pages.

### How it works

1. Make your initial request with `max_results`
2. Check the `meta` object for `next_token`
3. Include `next_token` in subsequent requests
4. Repeat until no `next_token` is returned

### Example

<CodeGroup>
  ```bash cURL theme={null}
  # First request
  curl "https://api.x.com/2/tweets/search/recent?query=python&max_results=100" \
    -H "Authorization: Bearer $BEARER_TOKEN"

  # Subsequent request with pagination token
  curl "https://api.x.com/2/tweets/search/recent?query=python&max_results=100&next_token=NEXT_TOKEN" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # The SDK handles pagination automatically
  all_posts = []

  for page in client.posts.search_recent(query="python", max_results=100):
      if page.data:
          all_posts.extend(page.data)

  print(f"Found {len(all_posts)} posts")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  async function getAllResults(query) {
    const allPosts = [];

    // The SDK handles pagination automatically
    const paginator = client.posts.searchRecent(query, { maxResults: 100 });

    for await (const page of paginator) {
      if (page.data) {
        allPosts.push(...page.data);
      }
    }

    return allPosts;
  }

  // Usage
  const posts = await getAllResults("python");
  console.log(`Found ${posts.length} posts`);
  ```
</CodeGroup>

<Card title="Pagination guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/posts/search/integrate/paginate">
  Learn more about pagination
</Card>

***

## Post edits

Posts can be edited up to 5 times within 30 minutes. The search endpoints always return the most recent version.

### Considerations

* `edit_history_tweet_ids` contains all Post IDs (oldest first)
* Posts fetched after the 30-minute window represent the final version
* For near-real-time use cases, recently-published Posts may still be edited

<Card title="Edit Posts fundamentals" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-history.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=6afe17587c08ee621e37afde19a07ff1" href="/x-api/fundamentals/edit-posts">
  Learn more about Post edits
</Card>

***

## Best practices

<CardGroup>
  <Card title="Start specific" icon="crosshairs">
    Use multiple operators to narrow results and reduce noise.
  </Card>

  <Card title="Test iteratively" icon="flask">
    Start broad, then refine based on results.
  </Card>

  <Card title="Handle pagination" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e">
    Implement proper pagination for large result sets.
  </Card>

  <Card title="Cache results" icon="database">
    Store results locally to avoid repeated requests.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="Build a query" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/search/integrate/build-a-query">
    Master query syntax
  </Card>

  <Card title="Operator reference" icon="list-check" href="/x-api/posts/search/integrate/operators">
    All available operators
  </Card>

  <Card title="Pagination" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/posts/search/integrate/paginate">
    Handle large result sets
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/recent-search">
    Full endpoint documentation
  </Card>
</CardGroup>


# Pagination
Source: https://docs.x.com/x-api/posts/search/integrate/paginate

Search queries typically match on more Posts than can be returned in a single API response. Reference for the X API v2 standard tier covering integrate.

### Recent search pagination

#### Introduction

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'. Pagination refers to methods for requesting all of the pages in order to retrieve the entire data set.

Here are fundamental recent search pagination details:

* The recent search endpoints will respond to a query with at least one page, and provide a next\_token in its JSON response if additional pages are available. To receive matching Posts, this process can be repeated until no token is included in the response.

* The next\_token does not expire. Multiple requests using the same next\_token value will receive the same results, regardless of when the request is made.

* Posts are delivered in reverse-chronological order, in the UTC timezone. This is true within individual pages, as well as across multiple pages: 
  * The first Post in the first response will be the most recent one matching your query.
  * The last Post in the last response will be the oldest one matching your query.

* The max\_results request parameter enables you to configure the number of Posts returned per response. This defaults to 10 Posts and has a maximum of 100. 

* Every pagination implementation will involve parsing next\_tokens from the response payload, and including them in the 'next page' search request. See below for more details on how to construct these 'next page' requests.
   

The recent search endpoint was designed to support two fundamental use patterns:

* **Get historical** - Requesting matching Posts from a time period of interest. These are typically one-time requests in support of historical research. Search requests can be based on start\_time and end\_time request parameters. recent search endpoint respond with Posts delivered in reverse-chronological order, starting with the most recent matching Post. 

* **Polling** - Requesting matching Posts that have been posted since the last Post received. These use cases often have a near-real-time focus and are characterized by frequent requests, "listening" for new Posts of interest. The recent search endpoint provide the since\_id request parameter in support of the 'polling' pattern. To help with navigating by Post IDs, the until\_id request parameter is also available.
   

Next, we'll discuss the historical mode. This is the default mode of the recent search endpoint and illustrates the fundamentals of pagination. Then we'll discuss examples of polling use cases. When polling triggers pagination, there is an additional step to manage search requests.
 

#### Retrieving historical data

This section outlines how you can retrieve Posts from a period of interest (currently limited to the last seven days) using the start\_time and end\_time request parameters. Historical requests are typically one-time requests in support of research and analysis. 

Making requests for a period of data is the default mode of the recent search endpoint. If a search request does not specify a start\_time, end\_time, or since\_id request parameter, the end\_time will default to "now" (actually 30 seconds before the time of query) and the start\_time will default to seven days ago.

The endpoint will respond with the first 'page' of Posts in reverse-chronological order, starting with the most recent Post. The response JSON payload will also include a next\_token if there are additional pages of data. To collect the entire set of matching Posts, regardless of the number of pages, requests are made until no next\_token is provided. 

For example, here is an initial request for Posts with the keyword snow from the last week:

[https://api.x.com/2/tweets/search/recent?query=snow](https://api.x.com/2/tweets/search/recent?query=snow)

The response includes the most recent 10 Posts, along with these "meta" attributes in the JSON response:

```
"meta": {
        "newest_id": "1204860593741553664",
        "oldest_id": "1204860580630278147",
        "next_token": "b26v89c19zqg8o3fobd8v73egzbdt3qao235oql",
        "result_count": 10
    }
```

To retrieve the next 10 Posts, this next\_token is added to the original request. The request would be:

[https://api.x.com/2/tweets/search/recent?query=snow\&next\_token=b26v89c19zqg8o3fobd8v73egzbdt3qao235oql](https://api.x.com/2/tweets/search/recent?query=snow\&next_token=b26v89c19zqg8o3fobd8v73egzbdt3qao235oql)

The process of looking for a next\_token and including it in a subsequent request can be repeated until all (or some number of) Posts are collected, or until a specified number of requests have been made. If data fidelity (collecting all matches of your query) is key to your use case, a simple "repeat until request.next\_token is null" design will suffice. 
 

#### Polling and listening use cases

This section outlines how you can retrieve recent Posts by polling the recent search endpoint with the since\_id request parameter. 

With polling use cases, "any new Posts of interest?" queries are made on an on-going, frequent basis. Unlike historical use cases, that base requests on time, polling use cases typically base requests on Post IDs.

Central to the polling use pattern is that every new Post has a [unique ID](/resources/fundamentals/x-ids) that is 'emitted' from the X platform generally in ascending order. If one Post has an ID smaller than another, it means it was posted earlier.

The recent search endpoint support navigating the Post archive by Post ID. Responses from the endpoint include oldest\_id and newest\_id Post IDs. In the polling mode, requests are made with the since\_id set to the largest/newest ID received so far. 

For example, say a query for new Posts about snow is made every five minutes, and the last Post we received had a Post ID of 10000. When it is time to poll, the request looks like:

[https://api.x.com/2/tweets/search/recent?query=snow\&since\_id=10000](https://api.x.com/2/tweets/search/recent?query=snow\&since_id=10000)

Next, let's say seven Posts were posted since our last request. Since all of these fit on a single data 'page', there is no next\_token. The response provides the Post ID of the most recent (newest) Post:

```
"meta": {
        "newest_id": "12000",
        "oldest_id": "10005",
        "result_count": 7
    }
```

To make the next polling query, this newest\_id value is used to set the next since\_id parameter:

`https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000`

When there is more data available, and next tokens are provided, only th newest\_id value from the first page of results is needed. Each page of data will include newest\_id and oldest\_id values, but the value provided in the first page is the only one needed for the next, regularly scheduled, polling request. So, If you are implementing a polling design, or searching for Posts by ID range, pagination logic is slightly more complicated. 

Now say that there are now 18 more matching Posts. The endpoint would respond with this initial response with a full data page and a next\_token for requesting the next page of data from this five minute period. It would also include the newest Post ID need for the next polling interval in five minutes.  

```
"meta": {
        "newest_id": "13800",
        "oldest_id": "12500",
        "next_token": "fnsih9chihsnkjbvkjbsc",
        "result_count": 10
    }
```

To collect all the matching data for this five minute period, pass the next\_token in your next request, along with the same since\_id value as the previous request.

[https://api.x.com/2/tweets/search/recent?query=snow\&since\\\_id=12000\&next\\\_token=fnsih9chihsnkjbvkjbsc](https://api.x.com/2/tweets/search/recent?query=snow\&since\\_id=12000\&next\\_token=fnsih9chihsnkjbvkjbsc)

```
"meta": {
        "newest_id": "12300",
        "oldest_id": "12010",
        "result_count": 8
    }
```

This second response provides the remaining eight Posts, and no next\_token. Note that we do not update our newest\_id value (12300), and instead base our next since\_id request on the first response's newest\_id value:

[https://api.x.com/2/tweets/search/recent?query=snow\&since\_id=13800](https://api.x.com/2/tweets/search/recent?query=snow\&since_id=13800)


# Search Posts
Source: https://docs.x.com/x-api/posts/search/introduction

The Search Posts endpoints let you find Posts matching specific criteria using powerful query. Reference for the X API v2 standard tier covering search.

The Search Posts endpoints let you find Posts matching specific criteria using powerful query operators. Search for keywords, hashtags, mentions, URLs, and more.

## Overview

X offers two search endpoints with different time ranges and access requirements:

<CardGroup>
  <Card title="Recent Search" icon="clock">
    Search Posts from the **last 7 days**. Available to all developers.
  </Card>

  <Card title="Full-Archive Search" icon="vault">
    Search the **complete archive** back to 2006. Available to pay-per-use and Enterprise customers.
  </Card>
</CardGroup>

***

## Use cases

* **Brand monitoring** — Track mentions of your brand or products
* **Trend analysis** — Analyze conversations around topics or events
* **Research** — Gather data for academic or market research
* **Real-time listening** — Build applications that react to new Posts

***

## Endpoints

| Method | Endpoint                                                      | Description                   | Access                  |
| :----- | :------------------------------------------------------------ | :---------------------------- | :---------------------- |
| GET    | [`/2/tweets/search/recent`](/x-api/posts/search-recent-posts) | Search Posts from last 7 days | All developers          |
| GET    | [`/2/tweets/search/all`](/x-api/posts/search-all-posts)       | Search complete Post archive  | Pay-per-use, Enterprise |

***

## Query operators

Build queries using operators that match on Post attributes:

```
(AI OR "artificial intelligence") lang:en -is:retweet has:links
```

<AccordionGroup>
  <Accordion title="Keyword operators">
    | Operator | Example              | Description                     |
    | :------- | :------------------- | :------------------------------ |
    | Keyword  | `python`             | Match Posts containing the word |
    | Phrase   | `"machine learning"` | Match exact phrase              |
    | Hashtag  | `#AI`                | Match Posts with hashtag        |
    | Mention  | `@XDevelopers`       | Match Posts mentioning user     |
  </Accordion>

  <Accordion title="User operators">
    | Operator       | Example          | Description                |
    | :------------- | :--------------- | :------------------------- |
    | `from:`        | `from:elonmusk`  | Posts by a user            |
    | `to:`          | `to:XDevelopers` | Replies to a user          |
    | `retweets_of:` | `retweets_of:X`  | Retweets of a user's Posts |
  </Accordion>

  <Accordion title="Content operators">
    | Operator       | Example          | Description             |
    | :------------- | :--------------- | :---------------------- |
    | `has:images`   | `cat has:images` | Posts with images       |
    | `has:videos`   | `has:videos`     | Posts with videos       |
    | `has:links`    | `has:links`      | Posts with links        |
    | `has:mentions` | `has:mentions`   | Posts with mentions     |
    | `url:`         | `url:github.com` | Posts with specific URL |
  </Accordion>

  <Accordion title="Filter operators">
    | Operator      | Example       | Description             |
    | :------------ | :------------ | :---------------------- |
    | `lang:`       | `lang:en`     | Posts in a language     |
    | `-is:retweet` | `-is:retweet` | Exclude retweets        |
    | `-is:reply`   | `-is:reply`   | Exclude replies         |
    | `is:verified` | `is:verified` | Posts by verified users |
  </Accordion>
</AccordionGroup>

<Card title="Full operator reference" icon="list-check" href="/x-api/posts/search/integrate/operators">
  See all available operators and their access requirements
</Card>

***

## Recent Search

Search Posts from the **last 7 days**. Available to all developers.

### Features

* Up to 100 Posts per request
* Pagination for large result sets
* All core query operators
* 512-character query length (4,096 for Enterprise)

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/search/quickstart/recent-search">
    Make your first recent search request
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/search-recent-posts">
    Full endpoint documentation
  </Card>
</CardGroup>

***

## Full-Archive Search

Search the **complete Post archive** dating back to March 2006.

<Note>
  Full-archive search is available to pay-per-use and Enterprise customers.
</Note>

### Features

* Up to 500 Posts per request
* Access to complete Post history
* All query operators available
* 1,024-character query length (4,096 for Enterprise)

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/search/quickstart/full-archive-search">
    Make your first full-archive search request
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/search-all-posts">
    Full endpoint documentation
  </Card>
</CardGroup>

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Build a query" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/search/integrate/build-a-query">
    Learn query syntax and operators
  </Card>

  <Card title="Pagination" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/posts/search/integrate/paginate">
    Navigate through large result sets
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/search/integrate/overview">
    Key concepts and best practices
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# v1 to v2 (Enterprise)
Source: https://docs.x.com/x-api/posts/search/migrate/enterprise-to-twitter-api-v2

Migrate from the Enterprise Search Posts API to X API v2 with a side-by-side comparison of pagination, timezones, Post edit history, and metadata fields.

### Enterprise compared to X API v2

**Similarities**

* Pagination
* Timezone
* Support for Post edit history and metadata. 

**Differences**

* Endpoint URLs
* App and Project requirement
* Available time periods
* Response data format
* HTTP methods
* Request time formats
* Request parameters
* Filtering operators

#### Similarities

**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).
 

**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.

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

* Enterprise endpoints:
  * 30 day - `http://gnip-api.x.com/search/30day/accounts/:account_name/:label.json`
  * Full-archive - `http://gnip-api.x.com/search/fullarchive/accounts/:account_name/:label.json`
* X API v2 endpoints
  * Recent (7 day) - `https://api.x.com/2/tweets/search/recent`
  * Full-archive - `https://api.x.com/2/tweets/search/all`

**App and Project requirement**

The X API v2 endpoints require that you use credentials from a Project 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


# Overview
Source: https://docs.x.com/x-api/posts/search/migrate/overview

The v2 Search Tweets endpoint will eventually replace the standard v1.1 search/posts endpoint and. Reference for the X API v2 standard tier covering migrate.

## 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.

***

## Recent search comparison

The following table compares the various types of recent search endpoints:

| **Description**                                                                                                                                                    | **Standard v1.1**                                                                                               | **X API v2**                                                                                                                                                                                                                                                                                                                                          |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Host domain                                                                                                                                                        | [https://api.x.com](https://api.x.com)                                                                          | [https://api.x.com](https://api.x.com)                                                                                                                                                                                                                                                                                                                |
| Endpoint path                                                                                                                                                      | /1.1/search/tweets.json                                                                                         | /2/tweets/search/recent                                                                                                                                                                                                                                                                                                                               |
| [Authentication](/resources/fundamentals/authentication)                                                                                                           | OAuth 1.0a User Context  <br />OAuth 2.0 App-Only                                                               | OAuth 1.0a User Context<br /><br />OAuth 2.0 Authorization Code with PKCE<br /><br />OAuth 2.0 App-Only                                                                                                                                                                                                                                               |
| Timestamp format                                                                                                                                                   | YYYYMMDD                                                                                                        | YYYY-MM-DDTHH:mm:ssZ  <br />[ISO 8601 / RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6)                                                                                                                                                                                                                                                    |
| Returns Posts that are no older than                                                                                                                               | 7 days                                                                                                          | 7 days                                                                                                                                                                                                                                                                                                                                                |
| HTTP methods supported                                                                                                                                             | GET                                                                                                             | GET                                                                                                                                                                                                                                                                                                                                                   |
| Default request rate limits                                                                                                                                        | 180 requests per 15 min with OAuth 1.0a User Context<br /><br />450 requests per 15 min with OAuth 2.0 App-Only | **Self-serve:**<br /><br />60 requests per 15 min with OAuth 2.0 App-Only<br /><br />60 requests per 15 min with OAuth 1.0a User Context<br /><br />60 requests per 15 min with OAuth 2.0 Authorization Code with PKCE                                                                                                                                |
| Offers fully unwound URLs                                                                                                                                          |                                                                                                                 | ✔                                                                                                                                                                                                                                                                                                                                                     |
| Maximum Posts per response (default)                                                                                                                               | 100 (15)                                                                                                        | 100 (10)                                                                                                                                                                                                                                                                                                                                              |
| Post 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)<br /><br />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/fields) return in the payload                                                                                |                                                                                                                 | ✔                                                                                                                                                                                                                                                                                                                                                     |
| Supports requesting and receiving [annotations](/x-api/fundamentals/post-annotations)                                                                              |                                                                                                                 | ✔                                                                                                                                                                                                                                                                                                                                                     |
| Supports requesting specific [metrics](/x-api/fundamentals/metrics) within Post object                                                                             |                                                                                                                 | ✔                                                                                                                                                                                                                                                                                                                                                     |
| Supports the [conversation\_id](/x-api/fundamentals/conversation-id) operator and field                                                                            |                                                                                                                 | ✔                                                                                                                                                                                                                                                                                                                                                     |
| Provides Post edit history                                                                                                                                         | ✔                                                                                                               | ✔                                                                                                                                                                                                                                                                                                                                                     |
| JSON key name for Post data array                                                                                                                                  | statuses                                                                                                        | data                                                                                                                                                                                                                                                                                                                                                  |
| JSON key name for pagination                                                                                                                                       | search\_metadata.next\_results                                                                                  | meta.next\_token                                                                                                                                                                                                                                                                                                                                      |
| Supports navigating archive by time range                                                                                                                          | ✔                                                                                                               | ✔                                                                                                                                                                                                                                                                                                                                                     |
| Time resolution of time-based requests                                                                                                                             | day                                                                                                             | second                                                                                                                                                                                                                                                                                                                                                |
| Timezone                                                                                                                                                           | UTC                                                                                                             | UTC                                                                                                                                                                                                                                                                                                                                                   |
| Request parameters for navigating by time                                                                                                                          | until                                                                                                           | start\_time  <br />end\_time                                                                                                                                                                                                                                                                                                                          |
| Request parameters for navigating by Post ID                                                                                                                       | since\_id   <br />max\_id                                                                                       | since\_id   <br />until\_id                                                                                                                                                                                                                                                                                                                           |
| Request parameter for pagination                                                                                                                                   | Provides URL-encoded query                                                                                      | next\_token                                                                                                                                                                                                                                                                                                                                           |
| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) |                                                                                                                 | ✔                                                                                                                                                                                                                                                                                                                                                     |

### Full-archive search 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://gnip-api.x.com)                                                                              | [https://api.x.com](https://api.x.com)                                                                          |
| Endpoint path                                                                                                                                                                                        | /search/fullarchive/accounts/:account\_name/:label                                                                            | /2/tweets/search/all                                                                                            |
| [Authentication](/resources/fundamentals/authentication)                                                                                                                                             | Basic auth                                                                                                                    | OAuth 2.0 App-Only                                                                                              |
| Timestamp format                                                                                                                                                                                     | YYYYMMDDHHMM                                                                                                                  | YYYY-MM-DDTHH:mm:ssZ  <br />[ISO 8601 / RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6)              |
| Returns Posts that are no older than                                                                                                                                                                 | The full archive since March 2006                                                                                             | The full archive since March 2006                                                                               |
| HTTP methods supported                                                                                                                                                                               | GET  <br />POST                                                                                                               | GET                                                                                                             |
| Default request rate limits                                                                                                                                                                          | The per minute rate limit will vary by partner as specified in your contract. <br /><br />20 requests per sec with Basic auth | 300 requests per 15 min with OAuth 2.0 App-Only<br /><br />1 requests per 1 sec with OAuth 2.0 App-Only         |
| Offers fully unwound URLs                                                                                                                                                                            | ✔                                                                                                                             | ✔                                                                                                               |
| Posts per response                                                                                                                                                                                   | Maximum: 500  <br />Default: 100                                                                                              | Maximum: 500  <br />Default: 10                                                                                 |
| Post JSON format                                                                                                                                                                                     | [Native Enriched or Activity Streams](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary) format                         | [X API v2](/x-api/fundamentals/data-dictionary) format (determined by fields and expansions request parameters) |
| Supports selecting which [fields](/x-api/fundamentals/fields) return in the payload                                                                                                                  |                                                                                                                               | ✔                                                                                                               |
| Supports requesting and receiving [annotations](/x-api/fundamentals/post-annotations)                                                                                                                |                                                                                                                               | ✔                                                                                                               |
| Supports requesting specific [metrics](/x-api/fundamentals/metrics) within Post object                                                                                                               |                                                                                                                               | ✔                                                                                                               |
| Supports the [conversation\_id](/x-api/fundamentals/conversation-id) operator and field                                                                                                              |                                                                                                                               | ✔                                                                                                               |
| Provides Post edit history                                                                                                                                                                           | ✔                                                                                                                             | ✔                                                                                                               |
| JSON key name for Post data array                                                                                                                                                                    | results                                                                                                                       | data                                                                                                            |
| JSON key name for pagination                                                                                                                                                                         | **next**                                                                                                                      | meta.next\_token                                                                                                |
| Time resolution of time-based requests                                                                                                                                                               | second                                                                                                                        | second                                                                                                          |
| Timezone                                                                                                                                                                                             | UTC                                                                                                                           | UTC                                                                                                             |
| Supports navigating archive by Post ID                                                                                                                                                               |                                                                                                                               | ✔                                                                                                               |
| Request parameters for navigation by time                                                                                                                                                            | fromDate  <br />toDate                                                                                                        | start\_time  <br />end\_time                                                                                    |
| Request parameters for navigating by Post ID                                                                                                                                                         |                                                                                                                               | since\_id   <br />until\_id                                                                                     |
| Request parameter for pagination                                                                                                                                                                     | next\_token                                                                                                                   | next\_token                                                                                                     |
| 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 |                                                                                                                               | ✔                                                                                                               |

**Filtering operator comparison**

The four different versions (standard, enterprise, and v2) of search Posts 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

X API v2

* **Self-serve:** Available when using any Project
* **Enterprise:** Available when using a Project

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#available-operators)
* [X API v2 operators](/x-api/posts/search/integrate/build-a-query#operators)

Now that we understand the different operator levels within X API v2, here is the table that maps out operator availability for search Posts (note that if the cell is left blank, the operator is not available):

| Search operator                     | Standard                                         | Enterprise | v2                                             |
| :---------------------------------- | :----------------------------------------------- | :--------- | :--------------------------------------------- |
| keyword                             | Available  <br />q:keyword                       | Available  | Available                                      |
| emoji                               | Available  <br />q:😄                            | Available  | Available                                      |
| "exact phrase"                      | Available                                        | Available  | Available                                      |
| #                                   | Available                                        | Available  | Available                                      |
| \$                                  | Available                                        | Available  | Available                                      |
| @                                   | Available                                        | Available  | Available                                      |
| from:                               | Available                                        | Available  | Available                                      |
| to:                                 | Available                                        | Available  | Available                                      |
| url:                                | Available                                        | Available  | Available                                      |
| retweets\_of:                       |                                                  | Available  | Available                                      |
| context:                            |                                                  |            | Available                                      |
| entity:                             |                                                  |            | Self-serve - Only available with recent search |
| conversation\_id:                   |                                                  |            | Available                                      |
| place:                              |                                                  | Available  | Available                                      |
| place\_country:                     |                                                  | Available  | Available                                      |
| point\_radius:                      | geocode parameter                                | Available  | Available                                      |
| bounding\_box:                      |                                                  | Available  | Available                                      |
| is:retweet                          | filter:retweets                                  | Available  | Available                                      |
| is:reply                            |                                                  | Available  | Available                                      |
| is:quote                            |                                                  | Available  | Available                                      |
| is:verified                         |                                                  | Available  | Available                                      |
| -is:nullcast                        |                                                  | Available  | Available                                      |
| has:hashtags                        |                                                  | Available  | Available                                      |
| has:cashtags                        |                                                  | Available  | Available                                      |
| has:links                           | filter:links                                     | Available  | Available                                      |
| has:mentions                        |                                                  | Available  | Available                                      |
| has:media                           | filter:media                                     | Available  | Available                                      |
| has:images                          | filter:images, filter:twimg                      | Available  | Available                                      |
| has:videos                          | filter:videos  <br />filter:native\_video        | Available  | Available                                      |
| has:geo                             |                                                  | Available  | Available                                      |
| lang:                               | lang - can be used as an operator or a parameter | Available  | Available                                      |
| has:profile\_geo                    |                                                  | Available  |                                                |
| profile\_country                    |                                                  | Available  |                                                |
| profile\_locality                   |                                                  | Available  |                                                |
| profile\_region                     |                                                  | Available  |                                                |
| proximity                           |                                                  | Available  |                                                |
| :(                                  | Available                                        |            |                                                |
| :)                                  | Available                                        |            |                                                |
| ?                                   | Available                                        |            |                                                |
| filter:periscope                    | Available                                        |            |                                                |
| list:                               | Available                                        |            | Available                                      |
| filter:replies                      | Available                                        |            |                                                |
| filter:pro\_video                   | Available                                        |            |                                                |
| filter:social                       | Available                                        |            |                                                |
| filter:trusted                      | Available                                        |            |                                                |
| filter:follows                      | Available                                        |            |                                                |
| filter:has\_engagement              | Available                                        |            |                                                |
| include:antisocial                  | Available                                        |            |                                                |
| include:offensive\_user             | Available                                        |            |                                                |
| include:antisocial\_offensive\_user | Available                                        |            |                                                |
| include:sensitive\_content          | Available                                        |            |                                                |
| source:                             | Available                                        |            |                                                |
| min\_replies:                       | Available                                        |            | Available                                      |
| min\_retweets:                      | Available                                        |            | Available as min\_reposts:                     |
| min\_faves:                         | Available                                        |            | Available as min\_likes:                       |
| card\_name:                         | Available                                        |            |                                                |
| card\_domain:                       | 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")

[Search Posts: Standard v1.1 to X API v2](/x-api/posts/search/migrate/standard-to-twitter-api-v2)

[Search Posts: Enterprise to X API v2](/x-api/posts/search/migrate/enterprise-to-twitter-api-v2)


# v1 to v2
Source: https://docs.x.com/x-api/posts/search/migrate/standard-to-twitter-api-v2

If you have been working with the v1.1 search/posts, the goal of this guide is to help you. Reference for the X API v2 standard tier covering migrate.

### 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.

* **Similarities**
  * OAuth 1.0a User Context and OAuth 2.0 App-Only
  * Support for Post edit history and metadata. 
* **Differences**
  * Endpoint URLs

  * App and Project requirements

  * Response data format

  * Request parameters

  * New query operators

  * AND / OR operator precedence 

#### Similarities

**OAuth 1.0a User Context and OAuth 2.0 App-Only authentication**

The v1.1 search/posts and the X API v2 recent search endpoint support both [OAuth 1.0a User Context](/resources/fundamentals/authentication) and [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0). 

Therefore, if you were previously using the standard v1.1 search endpoint 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 Access Token see this [OAuth 2.0 App-Only guide](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). 

If you would like to take advantage of the ability to pull private or advertising metrics with the X API v2 endpoint, you will need to use OAuth 1.0a User Context, and pass the user access tokens related to the user who posted the Post for which you would like to pull metrics. 

**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.


# Full-Archive Search Quickstart
Source: https://docs.x.com/x-api/posts/search/quickstart/full-archive-search

This guide walks you through making your first full-archive search request to find Posts from. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through making your first full-archive search request to find Posts from the complete X archive, dating back to March 2006.

<Warning>
  Full-archive search requires [Self-serve](/x-api/getting-started/about-x-api) or [Enterprise](/x-api/getting-started/about-x-api) access. [Upgrade your access](https://developer.x.com/en/portal/products) to use this endpoint.
</Warning>

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * Your App's Bearer Token (found in the Developer Console under "Keys and tokens")
</Note>

***

## Step 1: Build a query

Full-archive search supports all query operators. Build queries the same way as recent search:

```
from:XDevelopers lang:en
```

<Tip>
  Full-archive search supports queries up to 1,024 characters (4,096 for Enterprise).
</Tip>

***

## Step 2: Set a time range

By default, results return Posts from the last 30 days. Use `start_time` and `end_time` to search specific periods:

| Parameter    | Format   | Example                |
| :----------- | :------- | :--------------------- |
| `start_time` | ISO 8601 | `2020-01-01T00:00:00Z` |
| `end_time`   | ISO 8601 | `2020-12-31T23:59:59Z` |

***

## Step 3: Make a request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/tweets/search/all?\
  query=from%3AXDevelopers&\
  start_time=2020-01-01T00%3A00%3A00Z&\
  end_time=2020-12-31T23%3A59%3A59Z&\
  max_results=100" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Full-archive search with pagination
  for page in client.posts.search_all(
      query="from:XDevelopers",
      start_time="2020-01-01T00:00:00Z",
      end_time="2020-12-31T23:59:59Z",
      max_results=100
  ):
      for post in page.data:
          print(post.text)
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Full-archive search with pagination
  const paginator = client.posts.searchAll({
    query: "from:XDevelopers",
    startTime: "2020-01-01T00:00:00Z",
    endTime: "2020-12-31T23:59:59Z",
    maxResults: 100,
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(post.text);
    });
  }
  ```
</CodeGroup>

***

## Step 4: Review the response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "1271111223220809728",
      "text": "Tune in tonight and watch as @jessicagarson takes us through...",
      "edit_history_tweet_ids": ["1271111223220809728"]
    },
    {
      "id": "1270799243071062016",
      "text": "As we work towards building the new Twitter API...",
      "edit_history_tweet_ids": ["1270799243071062016"]
    }
  ],
  "meta": {
    "newest_id": "1271111223220809728",
    "oldest_id": "1270799243071062016",
    "result_count": 2
  }
}
```

<Note>
  Posts created before the edit feature was introduced (September 2022) won't include `edit_history_tweet_ids`.
</Note>

***

## Step 5: Add fields and expansions

Request additional data with query parameters:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/tweets/search/all?\
  query=from%3AXDevelopers&\
  start_time=2020-01-01T00%3A00%3A00Z&\
  end_time=2020-12-31T23%3A59%3A59Z&\
  tweet.fields=created_at,public_metrics,author_id&\
  expansions=author_id&\
  user.fields=username,description&\
  max_results=100" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Search with fields and expansions
  for page in client.posts.search_all(
      query="from:XDevelopers",
      start_time="2020-01-01T00:00:00Z",
      end_time="2020-12-31T23:59:59Z",
      tweet_fields=["created_at", "public_metrics", "author_id"],
      expansions=["author_id"],
      user_fields=["username", "description"],
      max_results=100
  ):
      for post in page.data:
          print(f"{post.created_at}: {post.text[:50]}...")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Search with fields and expansions
  const paginator = client.posts.searchAll({
    query: "from:XDevelopers",
    startTime: "2020-01-01T00:00:00Z",
    endTime: "2020-12-31T23:59:59Z",
    tweetFields: ["created_at", "public_metrics", "author_id"],
    expansions: ["author_id"],
    userFields: ["username", "description"],
    maxResults: 100,
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(`${post.created_at}: ${post.text?.slice(0, 50)}...`);
    });
  }
  ```
</CodeGroup>

***

## Step 6: Paginate through results

The SDKs handle pagination automatically. For cURL, use the `next_token` from the response:

```bash theme={null}
curl "https://api.x.com/2/tweets/search/all?\
query=from%3AXDevelopers&\
max_results=500&\
next_token=b26v89c19zqg8o3fo7gesq314yb9l2l4ptqy" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

<Card title="Pagination guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/posts/search/integrate/paginate">
  Learn more about navigating large result sets
</Card>

***

## Key differences from recent search

| Feature                 | Recent Search          | Full-Archive Search     |
| :---------------------- | :--------------------- | :---------------------- |
| Time range              | Last 7 days            | March 2006 to now       |
| Access required         | All developers         | Pay-per-use, Enterprise |
| Max results per request | 100                    | 500                     |
| Query length            | 512 chars              | 1,024 chars             |
| Rate limit              | 450 / 15 min           | 300 / 15 min, 1 / sec   |
| Authentication          | App-Only, User Context | App-Only                |

***

## Common parameters

| Parameter      | Description                | Default      |
| :------------- | :------------------------- | :----------- |
| `query`        | Search query (required)    | —            |
| `max_results`  | Posts per page (10-500)    | 10           |
| `start_time`   | Oldest Post timestamp      | 30 days ago  |
| `end_time`     | Newest Post timestamp      | Now          |
| `next_token`   | Pagination token           | —            |
| `tweet.fields` | Additional Post fields     | `id`, `text` |
| `expansions`   | Related objects to include | —            |

***

## Next steps

<CardGroup>
  <Card title="Build a query" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/search/integrate/build-a-query">
    Master query syntax and operators
  </Card>

  <Card title="Operator reference" icon="list-check" href="/x-api/posts/search/integrate/operators">
    See all available operators
  </Card>

  <Card title="Pagination guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/posts/search/integrate/paginate">
    Handle large result sets
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/full-archive-search">
    Full endpoint documentation
  </Card>
</CardGroup>


# Recent Search Quickstart
Source: https://docs.x.com/x-api/posts/search/quickstart/recent-search

This guide walks you through making your first recent search request to find Posts from the. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through making your first recent search request to find Posts from the last 7 days.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token (found in the Developer Console under "Keys and tokens")
</Note>

***

<Steps>
  <Step title="Build a query" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834">
    Search queries use operators to match Posts. Start with a simple keyword:

    ```
    python
    ```

    Or combine multiple operators:

    ```
    python lang:en -is:retweet
    ```

    This matches Posts containing "python" in English, excluding retweets.

    <Tip>
      See the [full operator reference](/x-api/posts/search/integrate/operators) for all available options.
    </Tip>
  </Step>

  <Step title="Make a request" icon="terminal">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/tweets/search/recent?query=python%20lang%3Aen%20-is%3Aretweet" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python Python SDK theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Search recent Posts
      for page in client.posts.search_recent(
          query="python lang:en -is:retweet"
      ):
          for post in page.data:
              print(post.text)
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Search recent Posts
      const paginator = client.posts.searchRecent({
        query: "python lang:en -is:retweet",
      });

      for await (const page of paginator) {
        page.data?.forEach((post) => {
          console.log(post.text);
        });
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response" icon="eye">
    The default response includes `id`, `text`, and `edit_history_tweet_ids`:

    ```json theme={null}
    {
      "data": [
        {
          "id": "1234567890123456789",
          "text": "Just started learning Python and loving it!",
          "edit_history_tweet_ids": ["1234567890123456789"]
        },
        {
          "id": "1234567890123456788",
          "text": "Python tip: use list comprehensions for cleaner code",
          "edit_history_tweet_ids": ["1234567890123456788"]
        }
      ],
      "meta": {
        "newest_id": "1234567890123456789",
        "oldest_id": "1234567890123456788",
        "result_count": 2
      }
    }
    ```
  </Step>

  <Step title="Add fields and expansions" icon="sliders">
    Request additional data with query parameters:

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/tweets/search/recent?\
      query=python%20lang%3Aen%20-is%3Aretweet&\
      tweet.fields=created_at,public_metrics,author_id&\
      expansions=author_id&\
      user.fields=username,verified&\
      max_results=10" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Search with fields and expansions
      for page in client.posts.search_recent(
          query="python lang:en -is:retweet",
          tweet_fields=["created_at", "public_metrics", "author_id"],
          expansions=["author_id"],
          user_fields=["username", "verified"],
          max_results=10
      ):
          for post in page.data:
              print(f"{post.text[:50]}... - Likes: {post.public_metrics.like_count}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Search with fields and expansions
      const paginator = client.posts.searchRecent({
        query: "python lang:en -is:retweet",
        tweetFields: ["created_at", "public_metrics", "author_id"],
        expansions: ["author_id"],
        userFields: ["username", "verified"],
        maxResults: 10,
      });

      for await (const page of paginator) {
        page.data?.forEach((post) => {
          console.log(`${post.text?.slice(0, 50)}... - Likes: ${post.public_metrics?.like_count}`);
        });
      }
      ```
    </CodeGroup>

    **Response:**

    ```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "data": [
        {
          "id": "1234567890123456789",
          "text": "Just started learning Python and loving it!",
          "created_at": "2024-01-15T10:30:00.000Z",
          "author_id": "9876543210",
          "public_metrics": {
            "retweet_count": 5,
            "reply_count": 2,
            "like_count": 42,
            "quote_count": 1
          },
          "edit_history_tweet_ids": ["1234567890123456789"]
        }
      ],
      "includes": {
        "users": [
          {
            "id": "9876543210",
            "username": "pythondev",
            "verified": false
          }
        ]
      },
      "meta": {
        "newest_id": "1234567890123456789",
        "oldest_id": "1234567890123456789",
        "result_count": 1
      }
    }
    ```
  </Step>

  <Step title="Paginate through results" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e">
    The SDKs handle pagination automatically. For cURL, use the `next_token` from the response:

    ```bash theme={null}
    curl "https://api.x.com/2/tweets/search/recent?\
    query=python&\
    max_results=100&\
    next_token=b26v89c19zqg8o3fo7gesq314yb9l2l4ptqy" \
      -H "Authorization: Bearer $BEARER_TOKEN"
    ```

    <Card title="Pagination guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/posts/search/integrate/paginate">
      Learn more about navigating large result sets
    </Card>
  </Step>
</Steps>

***

## Example queries

<AccordionGroup>
  <Accordion title="Posts from a specific user">
    ```
    from:XDevelopers
    ```
  </Accordion>

  <Accordion title="Posts with a hashtag">
    ```
    #Python -is:retweet
    ```
  </Accordion>

  <Accordion title="Posts with images">
    ```
    "machine learning" has:images lang:en
    ```
  </Accordion>

  <Accordion title="Posts mentioning a user">
    ```
    @elonmusk -is:retweet -is:reply
    ```
  </Accordion>

  <Accordion title="Posts with links to a domain">
    ```
    url:github.com lang:en
    ```
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup>
  <Card title="Build a query" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/posts/search/integrate/build-a-query">
    Master query syntax and operators
  </Card>

  <Card title="Operator reference" icon="list-check" href="/x-api/posts/search/integrate/operators">
    See all available operators
  </Card>

  <Card title="Full-archive search" icon="vault" href="/x-api/posts/search/quickstart/full-archive-search">
    Search the complete Post archive
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/posts/search-recent-posts">
    Full endpoint documentation
  </Card>
</CardGroup>


# Integration Guide
Source: https://docs.x.com/x-api/posts/timelines/integrate

This guide covers the key concepts you need to integrate the Timelines endpoints into your. Reference for the X API v2 standard tier covering timelines.

This guide covers the key concepts you need to integrate the Timelines endpoints into your application.

***

## Authentication

### Endpoint requirements

| Endpoint               | App-Only | User Context |
| :--------------------- | :------- | :----------- |
| User Posts timeline    | ✓        | ✓            |
| User mentions timeline | ✓        | ✓            |
| Home timeline          | —        | ✓ (required) |

### Private metrics

To access private metrics, you must authenticate on behalf of the Post author:

<Warning>
  These fields require User Context authentication:

  * `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`
</Warning>

***

## Fields and expansions

By default, responses include only `id`, `text`, and `edit_history_tweet_ids`. Request additional data:

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/123/tweets?\
  tweet.fields=created_at,public_metrics,author_id&\
  expansions=author_id,attachments.media_keys&\
  user.fields=username,verified&\
  media.fields=url,type" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get user's Posts timeline
  for page in client.posts.get_user_posts(
      user_id="123",
      tweet_fields=["created_at", "public_metrics", "author_id"],
      expansions=["author_id", "attachments.media_keys"],
      user_fields=["username", "verified"],
      media_fields=["url", "type"],
      max_results=100
  ):
      for post in page.data:
          print(f"{post.text} - {post.public_metrics}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get user's Posts timeline with pagination
  const paginator = client.posts.getUserPosts("123", {
    tweetFields: ["created_at", "public_metrics", "author_id"],
    expansions: ["author_id", "attachments.media_keys"],
    userFields: ["username", "verified"],
    mediaFields: ["url", "type"],
    maxResults: 100,
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(`${post.text} - ${JSON.stringify(post.public_metrics)}`);
    });
  }
  ```
</CodeGroup>

### Key fields

| Field                 | Description              |
| :-------------------- | :----------------------- |
| `created_at`          | Post creation timestamp  |
| `public_metrics`      | Engagement counts        |
| `conversation_id`     | Thread identifier        |
| `context_annotations` | Topic classifications    |
| `entities`            | Hashtags, mentions, URLs |

<Card title="Fields and expansions guide" icon="sliders" href="/x-api/fundamentals/fields">
  Learn more about customizing responses
</Card>

***

## Pagination

Timelines return up to 100 Posts per request. Use pagination for larger result sets.

### How it works

1. Make initial request with `max_results`
2. Get `next_token` from the `meta` object
3. Include `pagination_token` in next request
4. Repeat until no `next_token` is returned

### Example

<CodeGroup>
  ```bash cURL theme={null}
  # First request
  curl "https://api.x.com/2/users/123/tweets?max_results=100" \
    -H "Authorization: Bearer $BEARER_TOKEN"

  # Subsequent request with pagination token
  curl "https://api.x.com/2/users/123/tweets?max_results=100&pagination_token=NEXT_TOKEN" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # The SDK handles pagination automatically
  all_posts = []

  for page in client.posts.get_user_posts(user_id="123", max_results=100):
      if page.data:
          all_posts.extend(page.data)

  print(f"Found {len(all_posts)} posts")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  async function getAllTimelinePosts(userId) {
    const allPosts = [];

    // The SDK handles pagination automatically with async iteration
    const paginator = client.posts.getUserPosts(userId, { maxResults: 100 });

    for await (const page of paginator) {
      if (page.data) {
        allPosts.push(...page.data);
      }
    }

    return allPosts;
  }

  // Usage
  const posts = await getAllTimelinePosts("123");
  console.log(`Found ${posts.length} posts`);
  ```
</CodeGroup>

<Card title="Pagination guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/fundamentals/pagination">
  Learn more about pagination
</Card>

***

## Filtering results

### Time-based filtering

| Parameter    | Description                      |
| :----------- | :------------------------------- |
| `start_time` | Oldest Post timestamp (ISO 8601) |
| `end_time`   | Newest Post timestamp (ISO 8601) |
| `since_id`   | Return Posts after this ID       |
| `until_id`   | Return Posts before this ID      |

### Exclude parameter

Remove specific Post types from results:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/123/tweets?exclude=retweets,replies" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Exclude retweets and replies
  for page in client.posts.get_user_posts(
      user_id="123",
      exclude=["retweets", "replies"]
  ):
      for post in page.data:
          print(post.text)
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Exclude retweets and replies
  const paginator = client.posts.getUserPosts("123", {
    exclude: ["retweets", "replies"],
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => console.log(post.text));
  }
  ```
</CodeGroup>

| Value      | Effect           |
| :--------- | :--------------- |
| `retweets` | Exclude retweets |
| `replies`  | Exclude replies  |

***

## Volume limits

Each timeline has maximum retrieval limits:

| Endpoint                     | Maximum Posts     |
| :--------------------------- | :---------------- |
| User Posts timeline          | 3,200 most recent |
| User Posts (exclude=replies) | 800 most recent   |
| User mentions timeline       | 800 most recent   |
| Home timeline                | 3,200 or 7 days   |

<Note>
  Requesting Posts beyond these limits returns a successful response with no data.
</Note>

***

## Post edits

Posts can be edited up to 5 times within 30 minutes. Timeline endpoints always return the most recent version.

### Considerations

* Posts older than 30 minutes represent their final version
* Near-real-time use cases should account for potential edits
* Use Post lookup to verify final state if needed

<Card title="Edit Posts fundamentals" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-history.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=6afe17587c08ee621e37afde19a07ff1" href="/x-api/fundamentals/edit-posts">
  Learn more about Post edits
</Card>

***

## Post metrics

### Public metrics

Available for all Posts with App-Only or User Context authentication:

```json theme={null}
{
  "public_metrics": {
    "retweet_count": 156,
    "reply_count": 23,
    "like_count": 892,
    "quote_count": 12,
    "bookmark_count": 34,
    "impression_count": 15200
  }
}
```

### Private metrics

Requires User Context authentication from the Post author:

* Only available for Posts from the last 30 days
* Only returned for Posts authored by the authenticated user
* Returns error for other users' Posts

***

## Edge cases

<Accordion title="Non-public metrics and pagination">
  When requesting non-public metrics for Posts older than 30 days, you may receive a `next_token` with `result_count: 0`. To avoid this:

  * Keep requests within the last 30 days
  * Use `max_results` of at least 10
</Accordion>

<Accordion title="Promoted metrics for non-promoted Posts">
  Requesting promoted metrics for Posts that weren't promoted returns an empty response. This is a known issue.
</Accordion>

<Accordion title="Truncated Retweet text">
  For Retweets with text over 140 characters, the text field is truncated. Use the `referenced_tweets.id` expansion to get the full text.
</Accordion>

***

## Next steps

<CardGroup>
  <Card title="Home timeline quickstart" icon="house" href="/x-api/posts/timelines/quickstart/reverse-chron-quickstart">
    Get a user's home feed
  </Card>

  <Card title="Mentions quickstart" icon="at" href="/x-api/posts/timelines/quickstart/user-mention-quickstart">
    Get mentions for a user
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-posts">
    Full endpoint documentation
  </Card>

  <Card title="Pagination" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/fundamentals/pagination">
    Handle large result sets
  </Card>
</CardGroup>


# Timelines
Source: https://docs.x.com/x-api/posts/timelines/introduction

The Timelines endpoints let you retrieve Posts from user timelines, mention feeds, and home. Reference for the X API v2 standard tier covering timelines.

The Timelines endpoints let you retrieve Posts from user timelines, mention feeds, and home feeds. Get a user's posted content, see what Posts mention them, or view their personalized home timeline.

## Overview

<CardGroup>
  <Card title="User Posts" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305">
    Get Posts authored by a user
  </Card>

  <Card title="User mentions" icon="at">
    Get Posts mentioning a user
  </Card>

  <Card title="Home timeline" icon="house">
    Get personalized home feed
  </Card>

  <Card title="Reverse chronological" icon="clock">
    Posts in time order
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                                                    | Description                 |
| :----- | :-------------------------------------------------------------------------- | :-------------------------- |
| GET    | [`/2/users/:id/tweets`](/x-api/users/get-posts)                             | Get Posts by a user         |
| GET    | [`/2/users/:id/mentions`](/x-api/users/get-mentions)                        | Get Posts mentioning a user |
| GET    | [`/2/users/:id/timelines/reverse_chronological`](/x-api/users/get-timeline) | Get home timeline           |

***

## User Posts timeline

Get the most recent Posts authored by a specific user.

### Features

* Up to 3,200 most recent Posts
* Filter out replies and retweets
* Pagination support
* Historical access with time-based filtering

<CardGroup>
  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-posts">
    Full endpoint documentation
  </Card>
</CardGroup>

***

## User mentions timeline

Get Posts that mention a specific user.

### Features

* Up to 800 most recent mentions
* Includes replies and quote Posts
* Pagination support

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/timelines/quickstart/user-mention-quickstart">
    Get mentions for a user
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-mentions">
    Full endpoint documentation
  </Card>
</CardGroup>

***

## Reverse chronological home timeline

Get the authenticated user's home timeline in reverse chronological order.

### Features

* Posts from followed accounts
* Most recent 3,200 Posts (or 7 days)
* Excludes algorithmic ranking
* Requires user authentication

<Note>
  This endpoint requires [OAuth 1.0a User Context](/resources/fundamentals/authentication) or [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2).
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/timelines/quickstart/reverse-chron-quickstart">
    Get a user's home timeline
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-timeline">
    Full endpoint documentation
  </Card>
</CardGroup>

***

## Filtering options

### Exclude parameter

Filter out specific Post types:

| Value      | Effect           |
| :--------- | :--------------- |
| `retweets` | Exclude retweets |
| `replies`  | Exclude replies  |

```bash theme={null}
curl "https://api.x.com/2/users/123/tweets?exclude=retweets,replies" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

### Time-based filtering

| Parameter    | Description                      |
| :----------- | :------------------------------- |
| `start_time` | Oldest Post timestamp (ISO 8601) |
| `end_time`   | Newest Post timestamp (ISO 8601) |
| `since_id`   | Return Posts after this ID       |
| `until_id`   | Return Posts before this ID      |

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Home timeline quickstart" icon="house" href="/x-api/posts/timelines/quickstart/reverse-chron-quickstart">
    Get a user's home feed
  </Card>

  <Card title="Mentions quickstart" icon="at" href="/x-api/posts/timelines/quickstart/user-mention-quickstart">
    Get mentions for a user
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/timelines/integrate">
    Key concepts and best practices
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# Timelines endpoints migration overview
Source: https://docs.x.com/x-api/posts/timelines/migrate/overview

Map Standard v1.1 user and mention timelines to the X API v2 reverse chronological timeline and user mentions endpoints to plan your migration.

## Comparing X API's timelines endpoints

The v2 reverse chronological timeline, user Posts timeline, and user mention timeline endpoints replace the [v1.1 statuses/home\_timeline,](https://developer.x.com/en/docs/twitter-api/v1/tweets/timelines/api-reference/get-statuses-home_timeline) [v1.1 statuses/user\_timeline](https://developer.x.com/en/docs/twitter-api/v1/tweets/timelines/api-reference/get-statuses-user_timeline.html), and [v1.1 statuses/mentions\_timeline](https://developer.x.com/en/docs/twitter-api/v1/tweets/timelines/api-reference/get-statuses-mentions_timeline.html) endpoints respectively. If you have code, apps, or tools that use an older version of this endpoint and are considering migrating to the newer X API v2 endpoint, then this guide is for you.  For a more in-depth migration guide see [Standard v1.1 migration to X API v2](/x-api/posts/timelines/migrate/standard-to-twitter-api-v2).

This page contains three comparison tables:

* Reverse chronological home timeline
* User Post timeline
* User mention timeline

### Reverse chronological home timeline

The following tables compare the standard v1.1 and X API v2 home timeline endpoints:

|                                                                                                                                                                    |                                                                                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Description**                                                                                                                                                    | **Standard v1.1**                                                                                                                                      | **X API v2**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Documentation                                                                                                                                                      | [API Reference](https://developer.x.com/en/docs/twitter-api/v1/tweets/timelines/api-reference/get-statuses-home_timeline)                              | [API Reference](https://developer.x.com/x-api/posts/timelines#user-mention-timeline-3)                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| HTTP methods supported                                                                                                                                             | `GET`                                                                                                                                                  | `GET`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Host domain                                                                                                                                                        | `https://api.x.com`                                                                                                                                    | `https://api.x.com`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Endpoint paths                                                                                                                                                     | `/1.1/statuses/home_timeline.json`                                                                                                                     | `/2/users/:id/timelines/reverse_chronological`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Required parameters                                                                                                                                                | `user_id` or `screen_name`                                                                                                                             | User ID set as path parameter :id                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Authentication                                                                                                                                                     | OAuth 1.0a User Context                                                                                                                                | OAuth 1.0a User Context<br /><br />[OAuth 2.0 Authorization Code Flow with PKCE](/fundamentals/authentication/oauth-2-0/authorization-code)                                                                                                                                                                                                                                                                                                                                                                                              |
| Request rate limits                                                                                                                                                | 15 requests per 15-minute with OAuth 1.0a User Context<br /><br />Request cap: 100,000 within a 24 hour period.                                        | 180 requests per 15-minute window                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Default Posts per response                                                                                                                                         | 15                                                                                                                                                     | 100                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Maximum Posts per response                                                                                                                                         | 800                                                                                                                                                    | This endpoint returns every Post created on a timeline over the last 7 days as well as the most recent 800 regardless of creation date.                                                                                                                                                                                                                                                                                                                                                                                                  |
| Provides Post edit history                                                                                                                                         | ✔                                                                                                                                                      | ✔                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Historical Posts available                                                                                                                                         | The most recent 800 Posts, including Retweets                                                                                                          | The most recent 3,200 Posts, including Retweets                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Timeline navigation options                                                                                                                                        | since\_id (exclusive) used for update polling<br /><br />`max_id` (inclusive)                                                                          | `start_time`<br /><br />end\_time<br /><br />`since_id`(exclusive) used for update polling <br /><br />`until_id` (exclusive)                                                                                                                                                                                                                                                                                                                                                                                                            |
| Optional parameters for results refinement                                                                                                                         | `count`<br /><br />`exclude_replies`<br /><br />`include_rts`<br /><br />`trim_user`<br /><br />`tweet_mode`<br /><br />`since_id`<br /><br />`max_id` | `max_results`<br /><br />`exclude`(retweets,replies)<br /><br />`tweet.fields`<br /><br />`user.fields`<br /><br />`place.fields`<br /><br />`media.fields`<br /><br />`poll.fields`<br /><br />`expansions`<br /><br />`start_time`<br /><br />`end_time`<br /><br />`since_id`<br /><br />`until_id`                                                                                                                                                                                                                                   |
| Supports requesting and receiving [annotations](/x-api/fundamentals/post-annotations)                                                                              | N/A                                                                                                                                                    | If annotations are included in tweet.fields, results will be annotated with inferred annotation 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                                                                                                                                                    | If annotations are included in `tweet.fields`, results will be annotated with public\_metrics per Post including `retweet_count`, `reply_count`, `quote_count`, `like_count`, `impression_count`, and `bookmark_count`, `non_public_metrics` including `impression_count`, `user_profile_clicks`, `url_link_clicks`, and `engagements`.<br /><br />Additional media metrics such as view\_count and video playback metrics.<br /><br />Additional organic\_metrics and promoted\_metrics available with 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](https://developer.x.com/en/docs/twitter-api/v1/data-dictionary/overview.html)                                              | [X API v2](/x-api/fundamentals/data-dictionary) format (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)<br /><br />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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Results pagination                                                                                                                                                 | N/A must use navigation by Post ID                                                                                                                     | Results can be reviewed moving forward or backward using a pagination\_token                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) |                                                                                                                                                        | ✔                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

### User Post timeline

The following tables compare the standard v1.1 and X API v2 user Post timeline endpoints:

|                                                                                                                                                                    |                                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Description**                                                                                                                                                    | **Standard v1.1**                                                                                                                                                         | **X API v2**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Documentation                                                                                                                                                      | [API Reference](https://developer.x.com/en/docs/twitter-api/v1/tweets/timelines/api-reference/get-statuses-user_timeline.html)                                            | [API Reference](/x-api/users/get-posts)                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| HTTP methods supported                                                                                                                                             | GET                                                                                                                                                                       | GET                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Host domain                                                                                                                                                        | [https://api.x.com](https://api.x.com)                                                                                                                                    | [https://api.x.com](https://api.x.com)                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Endpoint paths                                                                                                                                                     | /1.1/statuses/user\_timeline.json                                                                                                                                         | /2/users/:id/tweets                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Required parameters                                                                                                                                                | user\_id or screen\_name                                                                                                                                                  | User ID set as path parameter :id                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Authentication                                                                                                                                                     | OAuth 1.0a User Context<br /><br />OAuth 2.0 App-Only                                                                                                                     | OAuth 1.0a User Context<br /><br />OAuth 2.0 App-Only<br /><br />OAuth 2.0 Authorization Code with PKCE                                                                                                                                                                                                                                                                                                                                                                                                              |
| Request rate limits                                                                                                                                                | 900 requests per 15 min with OAuth 1.0a User Context<br /><br />1500 requests per 15 min with OAuth 2.0 App-Only<br /><br />Request cap: 100,000 within a 24 hour period. | 900 requests per 15-minute window with OAuth 1.0a User Context<br /><br />1500 requests per 15-minute window with OAuth 2.0 App-Only                                                                                                                                                                                                                                                                                                                                                                                 |
| Default Posts per response                                                                                                                                         | 15                                                                                                                                                                        | 10                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Maximum Posts per response                                                                                                                                         | 200                                                                                                                                                                       | 100                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Historical Posts available                                                                                                                                         | The most recent 3,200 Posts, including Retweets                                                                                                                           | The most recent 3,200 Posts, including Retweets                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Timeline navigation options                                                                                                                                        | since\_id (exclusive) used for update polling<br /><br />max\_id (inclusive)                                                                                              | start\_time<br /><br />end\_time<br /><br />since\_id (exclusive) used for update polling <br /><br />until\_id (exclusive)                                                                                                                                                                                                                                                                                                                                                                                          |
| Optional parameters for results refinement                                                                                                                         | count  <br />exclude\_replies  <br />include\_rts  <br />trim\_user  <br />tweet\_mode  <br />since\_id  <br />max\_id                                                    | max\_results  <br />exclude(retweets,replies)  <br />tweet.fields  <br />user.fields  <br />place.fields  <br />media.fields  <br />poll.fields  <br />expansions  <br />start\_time  <br />end\_time  <br />since\_id  <br />until\_id                                                                                                                                                                                                                                                                              |
| Supports requesting and receiving [annotations](/x-api/fundamentals/post-annotations)                                                                              | N/A                                                                                                                                                                       | Returns Post results with inferred annotation 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.  <br />  <br />Available with OAuth1.0a User Context:  <br />Additional non\_public\_metrics , including impression\_count, user\_profile\_clicks, url\_link\_clicks.<br /><br />Additional media metrics such as view\_count and video playback metrics.<br /><br />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](/x-api/fundamentals/data-dictionary) format (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)<br /><br />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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Results pagination                                                                                                                                                 | N/A must use navigation by Post ID                                                                                                                                        | Results can be reviewed moving forward or backward using a 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                                                                                                                                         | ✔                                                                                                                                                                         | ✔                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

### User mention timeline

The following tables compare the standard v1.1 and X API v2 user mention timeline endpoints

|                                                                                        |                                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| :------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Description**                                                                        | **Standard v1.1**                                                                                                                  | **X API v2**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Documentation                                                                          | [API Reference](https://developer.x.com/en/docs/twitter-api/v1/tweets/timelines/api-reference/get-statuses-mentions_timeline.html) | [API Reference](/x-api/users/get-mentions)                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| HTTP methods supported                                                                 | GET                                                                                                                                | GET                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Host domain                                                                            | [https://api.x.com](https://api.x.com)                                                                                             | [https://api.x.com](https://api.x.com)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Endpoint paths                                                                         | /1.1/statuses/mentions\_timeline.json                                                                                              | /2/users/:id/mentions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Required parameters                                                                    | no required parameters                                                                                                             | User ID set as path parameter :id                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Authentication                                                                         | OAuth 1.0a User Context                                                                                                            | OAuth 1.0a User Context<br /><br />OAuth 2.0 App-Only<br /><br />OAuth 2.0 Authorization Code with PKCE                                                                                                                                                                                                                                                                                                                                                                                                               |
| Default request rate limits                                                            | 75 requests per 15 min with OAuth 1.0a User Context<br /><br />100,000 request cap within a 24 hour period.                        | 180 requests per 15-minute window with OAuth 1.0a User Context<br /><br />450 requests per 15-minute window with OAuth 2.0 App-Only                                                                                                                                                                                                                                                                                                                                                                                   |
| Default Posts per response                                                             | 15                                                                                                                                 | 10                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Maximum Posts per response                                                             | 200                                                                                                                                | 100                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Historical Posts available                                                             | The most recent 800 Posts                                                                                                          | The most recent 800 Posts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Timeline navigation options                                                            | since\_id (exclusive) used for update polling<br /><br />max\_id (inclusive)                                                       | start\_time<br /><br />end\_time<br /><br />since\_id (exclusive) used for update polling<br /><br />until\_id (exclusive)                                                                                                                                                                                                                                                                                                                                                                                            |
| Optional parameters for results refinement                                             | count  <br />trim\_user  <br />include\_entities  <br />tweet\_mode  <br />since\_id  <br />max\_id                                | max\_results  <br />tweet.fields  <br />user.fields  <br />place.fields  <br />media.fields  <br />poll.fields  <br />expansions  <br />start\_time  <br />end\_time  <br />since\_id  <br />until\_id                                                                                                                                                                                                                                                                                                                |
| Supports requesting and receiving [annotations](/x-api/fundamentals/post-annotations)  | N/A                                                                                                                                | Returns Posts results with inferred annotation 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.  <br />  <br />Available with OAuth 1.0a User Context:  <br />Additional non\_public\_metrics , including impression\_count, user\_profile\_clicks, url\_link\_clicks. <br /><br />Additional media metrics such as view\_count and video playback metrics.<br /><br />Additional organic\_metrics and promoted\_metrics available with OAuth 1.0a User Context for promoted Posts |
|                                                                                        |                                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |


# v1 to v2
Source: https://docs.x.com/x-api/posts/timelines/migrate/standard-to-twitter-api-v2

If you have been working with the v1.1 timelines endpoints (statuses/user\timeline and. Reference for the X API v2 standard tier covering migrate.

## Standard v1.1 timelines to X API v2 timelines

If you have been working with the v1.1 timelines endpoints (statuses/user\_timeline and statuses/mentions\_timeline), the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 timelines endpoints so that you can migrate your current integration to the new version.

* **Similarities:**
  * Authentication:
    * OAuth 1.0a User Context (reverse chronological home timeline, user Post timeline and user mentions timeline)
    * OAuth 2.0 App-Only (user Post timeline)
  * Historical Access limit: User timeline (user Post timeline) provides access to most recent 3200 Posts; mentions timeline (user mention timeline) provides access to most recent 800 mentions.
  * Support for Post edit history and metadata
  * Rate limits (user Post timeline)
  * Refresh polling: Ability to retrieve new results since the since\_id
  * Traversing timelines by Post IDs
  * Results specifications:
    * Results order: Results returned in reverse chronological order
    * Ability to exclude replies (user Post timeline only)
    * Ability to exclude Retweets (user Post timeline only)
* **Differences**
  * New Authentication capability:
    * OAuth 2.0 App-Only (user mention timeline)
    * OAuth 2.0 Authorization Code Flow with PKCE (reverse chronological home timeline, user Post timeline and user mentions timeline)
  * Access requirements: X API v2 App and Project requirements
  * Rate limits (user mention timeline and reverse chronological home timeline)
  * Additional pagination method
    * Different max\_results (count) per response
  * Response data format
  * Request parameters
    * Custom


# Home Timeline Quickstart
Source: https://docs.x.com/x-api/posts/timelines/quickstart/reverse-chron-quickstart

This guide walks you through making your first request to the reverse chronological home. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through making your first request to the reverse chronological home timeline endpoint.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Tokens (this endpoint requires user authentication)
</Note>

***

## Step 1: Get the user ID

You need the user ID for the account whose home timeline you want to retrieve. Find it using the username lookup endpoint:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/by/username/XDevelopers" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  response = client.users.get_by_username("XDevelopers")
  print(f"User ID: {response.data.id}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  const response = await client.users.getByUsername("XDevelopers");
  console.log(`User ID: ${response.data?.id}`);
  ```
</CodeGroup>

The response includes the user ID:

```json theme={null}
{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers"
  }
}
```

***

## Step 2: Request the home timeline

Make a GET request with the user ID and User Access Token:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/2244994945/timelines/reverse_chronological" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get home timeline with pagination
  for page in client.posts.get_home_timeline("2244994945"):
      for post in page.data:
          print(post.text)
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get home timeline with pagination
  const paginator = client.posts.getHomeTimeline("2244994945");

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(post.text);
    });
  }
  ```
</CodeGroup>

***

## Step 3: Review the response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "1524796546306478083",
      "text": "Today marks the launch of Devs in the Details...",
      "edit_history_tweet_ids": ["1524796546306478083"]
    },
    {
      "id": "1524468552404668416",
      "text": "Join us tomorrow for a discussion about bots...",
      "edit_history_tweet_ids": ["1524468552404668416"]
    }
  ],
  "meta": {
    "result_count": 2,
    "newest_id": "1524796546306478083",
    "oldest_id": "1524468552404668416",
    "next_token": "7140dibdnow9c7btw421dyz6jism75z99gyxd8egarsc4"
  }
}
```

***

## Step 4: Add fields and expansions

Request additional data with query parameters:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/2244994945/timelines/reverse_chronological?\
  tweet.fields=created_at,public_metrics,author_id&\
  expansions=author_id&\
  user.fields=username,verified&\
  max_results=10" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get home timeline with fields and expansions
  for page in client.posts.get_home_timeline(
      "2244994945",
      tweet_fields=["created_at", "public_metrics", "author_id"],
      expansions=["author_id"],
      user_fields=["username", "verified"],
      max_results=10
  ):
      for post in page.data:
          print(f"{post.text[:50]}... - Likes: {post.public_metrics.like_count}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get home timeline with fields and expansions
  const paginator = client.posts.getHomeTimeline("2244994945", {
    tweetFields: ["created_at", "public_metrics", "author_id"],
    expansions: ["author_id"],
    userFields: ["username", "verified"],
    maxResults: 10,
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(`${post.text?.slice(0, 50)}... - Likes: ${post.public_metrics?.like_count}`);
    });
  }
  ```
</CodeGroup>

***

## Step 5: Paginate through results

The SDKs handle pagination automatically. For cURL, use the `next_token` from the response to get more results:

```bash theme={null}
curl "https://api.x.com/2/users/2244994945/timelines/reverse_chronological?\
max_results=10&\
pagination_token=7140dibdnow9c7btw421dyz6jism75z99gyxd8egarsc4" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
```

***

## Common parameters

| Parameter     | Description                            | Default |
| :------------ | :------------------------------------- | :------ |
| `max_results` | Results per page (1-100)               | 10      |
| `start_time`  | Oldest Post timestamp (ISO 8601)       | —       |
| `end_time`    | Newest Post timestamp (ISO 8601)       | —       |
| `since_id`    | Return Posts after this ID             | —       |
| `until_id`    | Return Posts before this ID            | —       |
| `exclude`     | Exclude `retweets`, `replies`, or both | —       |

***

## Next steps

<CardGroup>
  <Card title="User mentions" icon="at" href="/x-api/posts/timelines/quickstart/user-mention-quickstart">
    Get Posts mentioning a user
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/timelines/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-timeline">
    Full endpoint documentation
  </Card>

  <Card title="Pagination guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/fundamentals/pagination">
    Navigate large result sets
  </Card>
</CardGroup>


# User Mentions Timeline
Source: https://docs.x.com/x-api/posts/timelines/quickstart/user-mention-quickstart

This guide walks you through retrieving Posts that mention a specific user. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through retrieving Posts that mention a specific user.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token (for public data) or User Access Token (for private metrics)
</Note>

***

## Get user mentions

<Steps>
  <Step title="Get the user ID">
    Find the user ID using the [user lookup endpoint](/x-api/users/lookup/introduction). For example, @XDevelopers has user ID `2244994945`.
  </Step>

  <Step title="Request the mentions timeline">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/users/2244994945/mentions?\
      tweet.fields=created_at,public_metrics,author_id&\
      expansions=author_id&\
      user.fields=username,verified&\
      max_results=10" \
        -H "Authorization: Bearer $BEARER_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_BEARER_TOKEN")

      # Get mentions timeline with pagination
      for page in client.posts.get_user_mentions(
          "2244994945",
          tweet_fields=["created_at", "public_metrics", "author_id"],
          expansions=["author_id"],
          user_fields=["username", "verified"],
          max_results=10
      ):
          for post in page.data:
              print(f"@{post.author_id}: {post.text[:50]}...")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

      // Get mentions timeline with pagination
      const paginator = client.posts.getUserMentions("2244994945", {
        tweetFields: ["created_at", "public_metrics", "author_id"],
        expansions: ["author_id"],
        userFields: ["username", "verified"],
        maxResults: 10,
      });

      for await (const page of paginator) {
        page.data?.forEach((post) => {
          console.log(`@${post.author_id}: ${post.text?.slice(0, 50)}...`);
        });
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": [
        {
          "id": "1301573587187331074",
          "text": "Hey @XDevelopers, love the new API!",
          "author_id": "1234567890",
          "created_at": "2024-01-15T10:30:00.000Z",
          "public_metrics": {
            "retweet_count": 5,
            "reply_count": 2,
            "like_count": 42,
            "quote_count": 1
          }
        }
      ],
      "includes": {
        "users": [
          {
            "id": "1234567890",
            "username": "developer",
            "name": "Dev Person",
            "verified": false
          }
        ]
      },
      "meta": {
        "newest_id": "1301573587187331074",
        "oldest_id": "1301573587187331074",
        "result_count": 1,
        "next_token": "t3buvdr5pujq9g7bggsnf3ep2ha28"
      }
    }
    ```
  </Step>
</Steps>

***

## Filter mentions

### Exclude replies

Get only original Posts that mention the user:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/2244994945/mentions?\
  exclude=replies&\
  max_results=10" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get mentions excluding replies
  for page in client.posts.get_user_mentions(
      "2244994945",
      exclude=["replies"],
      max_results=10
  ):
      for post in page.data:
          print(post.text)
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get mentions excluding replies
  const paginator = client.posts.getUserMentions("2244994945", {
    exclude: ["replies"],
    maxResults: 10,
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(post.text);
    });
  }
  ```
</CodeGroup>

### Get mentions in a time range

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/2244994945/mentions?\
  start_time=2024-01-01T00%3A00%3A00Z&\
  end_time=2024-01-31T23%3A59%3A59Z" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get mentions in a time range
  for page in client.posts.get_user_mentions(
      "2244994945",
      start_time="2024-01-01T00:00:00Z",
      end_time="2024-01-31T23:59:59Z"
  ):
      for post in page.data:
          print(f"{post.created_at}: {post.text[:50]}...")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get mentions in a time range
  const paginator = client.posts.getUserMentions("2244994945", {
    startTime: "2024-01-01T00:00:00Z",
    endTime: "2024-01-31T23:59:59Z",
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(`${post.created_at}: ${post.text?.slice(0, 50)}...`);
    });
  }
  ```
</CodeGroup>

***

## Common parameters

| Parameter          | Description                            | Default |
| :----------------- | :------------------------------------- | :------ |
| `max_results`      | Results per page (1-100)               | 10      |
| `start_time`       | Oldest Post timestamp (ISO 8601)       | —       |
| `end_time`         | Newest Post timestamp (ISO 8601)       | —       |
| `since_id`         | Return Posts after this ID             | —       |
| `until_id`         | Return Posts before this ID            | —       |
| `exclude`          | Exclude `retweets`, `replies`, or both | —       |
| `pagination_token` | Token for next page                    | —       |

***

## Next steps

<CardGroup>
  <Card title="Home timeline" icon="house" href="/x-api/posts/timelines/quickstart/reverse-chron-quickstart">
    Get user's home timeline
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/timelines/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-mentions">
    Full endpoint documentation
  </Card>

  <Card title="Pagination guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/fundamentals/pagination">
    Navigate large result sets
  </Card>
</CardGroup>


# Volume streams (1% sampled and Decahose) on the X API v2
Source: https://docs.x.com/x-api/posts/volume-streams/introduction

Stream sampled Posts in real time with the X API v2 1% sampled stream and 10% Decahose volume stream endpoints to track trends, sentiment, and events.

* 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/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. 

*To use these APIs, you must first set up an account with our enterprise sales team.*

<Note>
  **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).
</Note>

<div>
  <Button href="/x-api/posts/volume-streams/quickstart">
    Quick start
  </Button>

  <Button href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Sample code
  </Button>

  <Button href="https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80">
    Run in Postman
  </Button>

  <Button href="https://developer.x.com/apitools/api?endpoint=/2/tweets/sample/stream&method=get">
    Try with API Explorer
  </Button>
</div>

***

## Streaming fundamentals

<CardGroup>
  <Card title="Consuming streaming data" icon="stream" href="/x-api/fundamentals/consuming-streaming-data">
    Best practices for streaming clients
  </Card>

  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Reconnect gracefully
  </Card>

  <Card title="High volume capacity" icon="gauge-high" href="/x-api/fundamentals/high-volume-capacity">
    Handle high throughput
  </Card>

  <Card title="Recovery and redundancy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055" href="/x-api/fundamentals/recovery-and-redundancy">
    Build resilient applications
  </Card>
</CardGroup>


# Handling disconnections
Source: https://docs.x.com/x-api/powerstream/handling-disconnections

Handle disconnections, reconnects, and backfill on the X API v2 Powerstream endpoint with guidance on retries, error codes, and stream stability.

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

The core concepts for handling disconnections apply to all streaming endpoints. See the fundamentals guide for:

* Why connections disconnect
* Common disconnection errors
* Detecting disconnections
* Reconnection strategies and backoff
* Best practices

## Recovering lost data

If you experience a disconnect, see [Recovery and redundancy](/x-api/fundamentals/recovery-and-redundancy) for strategies to recover missed data, including:

* **Backfill** — Use the `backfillMinutes` parameter for disconnections of 5 minutes or less
* **Recovery** — Use `startTime` and `endTime` parameters for longer disconnections (up to 24 hours)

### Powerstream backfill example

```bash theme={null}
curl 'https://api.x.com/2/powerstream?backfillMinutes=5' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Powerstream recovery example

```bash theme={null}
curl 'https://api.x.com/2/powerstream?startTime=2022-07-12T15:10:00Z&endTime=2022-07-12T15:20:00Z' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

***

## Next steps

<CardGroup>
  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Complete disconnection handling guide
  </Card>

  <Card title="Recovery and redundancy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055" href="/x-api/fundamentals/recovery-and-redundancy">
    Recover missed data
  </Card>

  <Card title="Consuming streaming data" icon="stream" href="/x-api/fundamentals/consuming-streaming-data">
    Build robust streaming clients
  </Card>
</CardGroup>


# Powerstream low-latency streaming API on the X API v2
Source: https://docs.x.com/x-api/powerstream/introduction

Powerstream is the X API v2 lowest-latency streaming endpoint for public Post data, using PowerTrack-style rules to filter by keywords, operators, and metadata.

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.

Currently, Powerstream supports up to 1,000 rules and each rule can be 2048 characters.

## Key features

* **Real-time data delivery**: Lowest latency option for streaming Posts as they're published.
* **Precise filtering**: Filter for exactly the data you are looking for using Boolean queries with operators.
* **Delivery**: JSON response over HTTP/1.1 chunked transfer encoding.
* **Local datacenter support**: Fetch Posts only from the local datacenter to further reduce latency by avoiding replication lag.

<Note>
  The Powerstream API is a premium offering available under select Enterprise plans.

  If you're interested in accessing Powerstream or learning more about our Enterprise offerings, please reach out to our Sales team by submitting the [Enterprise Request Form](/forms/enterprise-api-interest).
  We'll be happy to discuss how Powerstream can support your needs.
</Note>

## Quick start

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 theme={null}
import requests
import json
import time
import sys
import os  # For env vars
```

### Setup

```python theme={null}
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 title="Example" lines wrap icon="python" theme={null}
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 title="Example" lines wrap icon="python" theme={null}
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 theme={null}
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 title="Example" lines wrap icon="python" theme={null}
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 theme={null}
# 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 theme={null}
'x-powerstream-datacenter': 'atla',
'x-powerstream-localdconly': 'true'
```

In addition to this, it will also send an initial payload specifying the datacenter:

```bash theme={null}
{
    "type": "connection_metadata",
    "datacenter": "atla",
    "timestamp": 1762557264155
}
```

<Note>
  **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.
</Note>

## Operators

In order to set rules for filtering, you can use keywords and operators.

<Card title="Powerstream operators" icon="list-check" href="/x-api/powerstream/operators">
  Complete list of available operators
</Card>

***

## Responses

The payload of the Powerstream API is the same format as the legacy GNIP Powertrack API. A sample json response looks like:

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
[
   {
       "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": "<a href=\"http://x.com\" rel=\"nofollow\">X Web Client</a>",
       "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 and 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

<CardGroup>
  <Card title="Consuming streaming data" icon="stream" href="/x-api/fundamentals/consuming-streaming-data">
    Best practices for streaming clients
  </Card>

  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Reconnect gracefully
  </Card>

  <Card title="High volume capacity" icon="gauge-high" href="/x-api/fundamentals/high-volume-capacity">
    Handle high throughput
  </Card>

  <Card title="Recovery and redundancy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055" href="/x-api/fundamentals/recovery-and-redundancy">
    Build resilient applications
  </Card>
</CardGroup>


# Powerstream Operators
Source: https://docs.x.com/x-api/powerstream/operators

This page provides a complete list of operators available when building rules for. Reference for the X API v2 standard tier covering powerstream.

This page provides a complete list of operators available when building rules for [Powerstream](/x-api/powerstream/introduction).

## Overview

Powerstream uses Boolean queries with operators to filter Posts based on keywords and metadata. Rules can be up to 2,048 characters and you can have up to 1,000 rules.

***

## User operators

| Operator       | Summary                                   | Example                             |
| :------------- | :---------------------------------------- | :---------------------------------- |
| `from:`        | Matches posts from a specific user        | `from:xdevelopers` or `from:123456` |
| `to:`          | Matches posts directed to a specific user | `to:jvaleski`                       |
| `retweets_of:` | Matches reposts of a specific user        | `retweets_of:xdevelopers`           |

***

## Content operators

| Operator        | Summary                                          | Example                                  |
| :-------------- | :----------------------------------------------- | :--------------------------------------- |
| `contains:`     | Matches posts containing specific text/keywords  | `contains:hello` or `contains:-2345.432` |
| `url_contains:` | Matches posts with URLs containing specific text | `url_contains:"com/willplayforfood"`     |
| `lang:`         | Matches posts in specific languages              | `lang:en`                                |

***

## Entity operators

| Operator | Summary                                       | Example                                 |
| :------- | :-------------------------------------------- | :-------------------------------------- |
| `has:`   | Matches posts containing specific entities    | `has:images`, `has:geo`, `has:mentions` |
| `is:`    | Matches posts of specific types or properties | `is:retweet`, `is:reply`                |

### Available `has:` options

* `has:mentions` — Posts that mention another user
* `has:geo` — Posts with geolocation data
* `has:links` — Posts containing links
* `has:media` — Posts containing media
* `has:lang` — Posts with detected language
* `has:symbols` — Posts containing cashtags
* `has:images` — Posts containing images
* `has:videos` — Posts containing videos

### Available `is:` options

* `is:retweet` — Retweets
* `is:reply` — Replies to other posts

***

## Location operators

| Operator        | Summary                                        | Example                                                                                    |
| :-------------- | :--------------------------------------------- | :----------------------------------------------------------------------------------------- |
| `place:`        | Matches posts from specific places/locations   | `place:"Belmont Central"` or `place:02763fa2a7611cf3`                                      |
| `bounding_box:` | Matches posts within a geographic bounding box | `bounding_box:[-112.424083 42.355283 -112.409111 42.792311]`                               |
| `point_radius:` | Matches posts within a radius of a point       | `point_radius:[-111.464973 46.371179 25mi]` or `point_radius:[-111.464973 46.371179 15km]` |

***

## User profile operators

| Operator    | Summary                                            | Example                |
| :---------- | :------------------------------------------------- | :--------------------- |
| `bio:`      | Matches posts from users with specific bio content | `bio:"data scientist"` |
| `bio_name:` | Matches posts from users with specific name in bio | `bio_name:PhD`         |

***

## Post reference operators

| Operator                 | Summary                           | Example                                     |
| :----------------------- | :-------------------------------- | :------------------------------------------ |
| `retweets_of_status_id:` | Matches reposts of specific posts | `retweets_of_status_id:1234567890123456789` |
| `in_reply_to_status_id:` | Matches replies to specific posts | `in_reply_to_status_id:1234567890123456789` |

***

## Special syntax operators

| Operator   | Summary               | Example          |
| :--------- | :-------------------- | :--------------- |
| `@`        | Mention operator      | `@username`      |
| `"phrase"` | Matches exact phrases | `"exact phrase"` |

***

## Logical operators

| Operator  | Summary                          | Example                                   |
| :-------- | :------------------------------- | :---------------------------------------- |
| `OR`      | Logical OR between expressions   | `x OR facebook`                           |
| Space/AND | Logical AND between expressions  | `x facebook` (both terms must be present) |
| `()`      | Grouping for complex expressions | `(x OR facebook) iphone`                  |
| `-`       | Negation/exclusion               | `x -facebook` (x but not facebook)        |

***

## Building rules

### Basic examples

```
# Match posts from a specific user

from:xdevelopers

# Match posts containing keywords

contains:API contains:developer

# Match posts with images in English

has:images lang:en
```

### Combining operators

```
# Posts from @xdevelopers OR @api that aren't retweets

(from:xdevelopers OR from:api) -is:retweet

# Posts mentioning AI with images, excluding retweets

contains:AI has:images -is:retweet lang:en

# Posts within 25 miles of a location

point_radius:[-73.935242 40.730610 25mi] lang:en
```

***

## Next steps

<CardGroup>
  <Card title="Powerstream introduction" icon="bolt" href="/x-api/powerstream/introduction">
    Get started with Powerstream
  </Card>

  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Handle streaming disconnections
  </Card>

  <Card title="Recovery and redundancy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055" href="/x-api/fundamentals/recovery-and-redundancy">
    Recover missed data
  </Card>
</CardGroup>


# Recovery and redundancy
Source: https://docs.x.com/x-api/powerstream/recovery-and-redundancy

This page covers Powerstream-specific recovery and redundancy features. Reference for the X API v2 standard tier covering powerstream.

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

The core concepts for recovery and redundancy apply to all streaming endpoints. See the fundamentals guide for:

* Redundant connections
* Backfill vs. Recovery decision tree
* Best practices

## Backfill

For disconnections of **5 minutes or less**, use the `backfillMinutes` parameter:

```bash theme={null}
curl 'https://api.x.com/2/powerstream?backfillMinutes=5' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

<Note>
  Older Posts are delivered first. Posts are **not** deduplicated — your system should be tolerant of duplicates.
</Note>

## Recovery

For disconnections **longer than 5 minutes** (up to 24 hours), use the `startTime` and `endTime` parameters:

| Parameter   | Type          | Description                      |
| :---------- | :------------ | :------------------------------- |
| `startTime` | ISO 8601 date | Start time to recover from (UTC) |
| `endTime`   | ISO 8601 date | End time to recover to (UTC)     |

```bash theme={null}
curl 'https://api.x.com/2/powerstream?startTime=2022-07-12T15:10:00Z&endTime=2022-07-12T15:20:00Z' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Once connected, Recovery will re-stream the specified time period, then disconnect.

***

## Next steps

<CardGroup>
  <Card title="Recovery and redundancy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055" href="/x-api/fundamentals/recovery-and-redundancy">
    Complete recovery guide
  </Card>

  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Handle streaming disconnections
  </Card>

  <Card title="Consuming streaming data" icon="stream" href="/x-api/fundamentals/consuming-streaming-data">
    Build robust streaming clients
  </Card>
</CardGroup>


# Get Spaces by ID
Source: https://docs.x.com/x-api/spaces/get-space-by-id

get /2/spaces/{id}



# Get Space Posts
Source: https://docs.x.com/x-api/spaces/get-space-posts

get /2/spaces/{id}/tweets
Retrieves a list of Posts shared in a specific Space by its ID.



# Get Space ticket buyers
Source: https://docs.x.com/x-api/spaces/get-space-ticket-buyers

get /2/spaces/{id}/buyers
Retrieves a list of Users who purchased tickets to a specific Space by its ID.



# Get Spaces by Creator IDs
Source: https://docs.x.com/x-api/spaces/get-spaces-by-creator-ids

get /2/spaces/by/creator_ids



# Get Spaces by ID
Source: https://docs.x.com/x-api/spaces/get-spaces-by-id

get /2/spaces/{id}



# Get Spaces by IDs
Source: https://docs.x.com/x-api/spaces/get-spaces-by-ids

get /2/spaces



# Spaces endpoints on the X API v2
Source: https://docs.x.com/x-api/spaces/introduction

Use the X API v2 Spaces endpoints to look up live or scheduled audio Spaces, search by keyword, and inspect creators, hosts, speakers, and listener details.

The following page describes the Spaces endpoints included in the X API. To learn more about Spaces in general, please visit [help.x.com](https://help.x.com/en/using-twitter/spaces). 

Spaces allow expression and interaction via live audio conversation. The Spaces endpoints provide the tools to create new functionality around Spaces. You can use these endpoints to lookup live or scheduled Spaces, or to build discovery experiences to give your users ways to find Spaces they may be interested in.

We encourage you to use your creativity to extend Spaces beyond the way we built it. With these endpoints you can build experiences to suggest Spaces to listeners based on keywords present in the title, or by surfacing accounts who host live or upcoming Spaces and are followed by a user; you can also help Hosts better understand how their Spaces are performing and get more insights on their audience.
 

### Important resources

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/reference#space)
* [Make your first request to a Spaces endpoint](/x-api/spaces/lookup/introduction)

   

#### What's currently available

|                   |                                                                                                                                                                                                                                                                                                                                                                                                 |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Spaces lookup** | [Lookup by a single Spaces ID](/x-api/spaces/space-lookup-by-space-id)<br /><br />[Lookup using multiple Spaces IDs](/x-api/spaces/space-lookup-up-space-ids)<br /><br />[Lookup by their creator ID](/x-api/spaces/space-lookup-by-their-creators)<br /><br />[Lookup list of user who purchased a ticket](/x-api/spaces/retrieve-the-list-of-users-who-purchased-a-ticket-to-the-given-space) |
| **Search Spaces** | [Search for spaces using a keyword](/x-api/spaces/search-for-spaces)                                                                                                                                                                                                                                                                                                                            |

#### Understanding the lifecycle of Spaces

Unlike other resources of the X Developer Platform, Spaces have a set lifecycle. Spaces can be scheduled up to 14 days in advance of their intended start date, and become unavailable after they end. A host can also cancel a previously scheduled Space anytime before it starts.

Spaces are accessible while they are live; once ended, they will no longer be available for retrieval using the Spaces endpoints, and an error message will be returned to indicate this condition.

When your app handles Spaces data, you are responsible for returning the most up-to-date information, and that you remove data that is no longer available from the platform. The [Spaces lookup endpoint](/x-api/spaces/lookup/introduction) can help you ensure you respect the expectations and intent of your users.
 

### Roles in Spaces

These endpoints reflect the way Spaces work on the X app. In Spaces, X users can have defined roles depending on how they interact with and interact in a Space.
 

### 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/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

The primary Hosts can make one or more users co-hosts. In the Spaces data dictionary, these Hosts will appear as host\_ids, which can be expanded into a list of user objects. Host designation can change throughout the duration of a Space, and the metadata returned by these endpoints will reflect the status at the time of the request.

Your app will know the primary host by checking the creator\_id value, and who are the co-hosts by checking the host\_ids values.
 

### Speaker

Speakers are users who have permission to talk in the Space. Zero or more Speakers can be present at any time, and there may be up to 10 Speakers (including the Hosts) in a Space. In the Space data dictionary, speakers will be returned in the speaker\_ids list, which you can expand into a list of user objects.
 

### Listener

A Listener can listen to a Space, react anytime using the predefined reactions, and ask to become a speaker (when the Hosts allows this in the Space settings). Listener information will only be returned as an aggregate count of participants (including Hosts) in the participant\_count field.


# Spaces Lookup
Source: https://docs.x.com/x-api/spaces/lookup/introduction

The Spaces lookup endpoints let you retrieve information about live or scheduled Spaces. Reference for the X API v2 standard tier covering lookup.

The Spaces lookup endpoints let you retrieve information about live or scheduled Spaces. Look up Spaces by their ID or find Spaces created by specific users.

## Overview

<CardGroup>
  <Card title="By ID" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-microphone.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=84616ff8f3d942047a71ee5e0a5adab9">
    Get details for a specific Space
  </Card>

  <Card title="Multiple Spaces" icon="microphone-lines">
    Look up multiple Spaces at once
  </Card>

  <Card title="By creator" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305">
    Find Spaces by their hosts
  </Card>

  <Card title="Buyers" icon="ticket">
    Get users who purchased tickets
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                                              | Description                    |
| :----- | :-------------------------------------------------------------------- | :----------------------------- |
| GET    | [`/2/spaces/:id`](/x-api/spaces/get-space-by-id)                      | Get Space by ID                |
| GET    | [`/2/spaces`](/x-api/spaces/get-spaces-by-ids)                        | Get Spaces by IDs              |
| GET    | [`/2/spaces/by/creator_ids`](/x-api/spaces/get-spaces-by-creator-ids) | Get Spaces by creator user IDs |
| GET    | [`/2/spaces/:id/buyers`](/x-api/spaces/get-space-ticket-buyers)       | Get ticket buyers for a Space  |
| GET    | [`/2/spaces/:id/tweets`](/x-api/spaces/get-space-posts)               | Get Posts shared in a Space    |

***

## Response fields

By default, the response includes `id` and `state`. Request additional fields:

| Field               | Description               |
| :------------------ | :------------------------ |
| `title`             | Space title               |
| `host_ids`          | Host user IDs             |
| `speaker_ids`       | Speaker user IDs          |
| `participant_count` | Number of participants    |
| `scheduled_start`   | Scheduled start time      |
| `started_at`        | Actual start time         |
| `ended_at`          | End time                  |
| `is_ticketed`       | Whether Space has tickets |

### Space states

| State       | Description          |
| :---------- | :------------------- |
| `live`      | Currently active     |
| `scheduled` | Scheduled for future |
| `ended`     | Has ended            |

***

## Example request

```bash theme={null}
curl "https://api.x.com/2/spaces/1DXxyRYNejbKM?\
space.fields=title,host_ids,participant_count,scheduled_start,state" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/spaces/lookup/quickstart">
    Make your first Spaces lookup request
  </Card>

  <Card title="Search Spaces" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/spaces/search/introduction">
    Find Spaces by keyword
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/spaces/space-lookup-by-space-id">
    Full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.x.com/x-api/spaces/lookup/quickstart

This guide walks you through retrieving Space information using the Spaces lookup endpoints. Reference for the X API v2 standard tier covering lookup.

This guide walks you through retrieving Space information using the Spaces lookup endpoints.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token
</Note>

***

## Get a Space by ID

Retrieve details for a specific Space:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/spaces/1DXxyRYNejbKM?\
  space.fields=title,host_ids,participant_count,scheduled_start,state,created_at" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get a Space by ID
  response = client.spaces.get(
      "1DXxyRYNejbKM",
      space_fields=["title", "host_ids", "participant_count", "scheduled_start", "state", "created_at"]
  )

  print(f"Space: {response.data.title}")
  print(f"State: {response.data.state}")
  print(f"Participants: {response.data.participant_count}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get a Space by ID
  const response = await client.spaces.get("1DXxyRYNejbKM", {
    spaceFields: ["title", "host_ids", "participant_count", "scheduled_start", "state", "created_at"],
  });

  console.log(`Space: ${response.data?.title}`);
  console.log(`State: ${response.data?.state}`);
  console.log(`Participants: ${response.data?.participant_count}`);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": {
    "id": "1DXxyRYNejbKM",
    "state": "live",
    "title": "Discussing AI and the Future",
    "host_ids": ["2244994945"],
    "participant_count": 245,
    "created_at": "2024-01-15T09:00:00.000Z"
  }
}
```

***

## Get multiple Spaces

Look up multiple Spaces at once:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/spaces?\
  ids=1DXxyRYNejbKM,1YqJDqWYNQDGW&\
  space.fields=title,state,participant_count" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get multiple Spaces
  response = client.spaces.get_spaces(
      ids=["1DXxyRYNejbKM", "1YqJDqWYNQDGW"],
      space_fields=["title", "state", "participant_count"]
  )

  for space in response.data:
      print(f"{space.title} - {space.state}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get multiple Spaces
  const response = await client.spaces.getSpaces({
    ids: ["1DXxyRYNejbKM", "1YqJDqWYNQDGW"],
    spaceFields: ["title", "state", "participant_count"],
  });

  response.data?.forEach((space) => {
    console.log(`${space.title} - ${space.state}`);
  });
  ```
</CodeGroup>

***

## Get Spaces by creator

Find Spaces hosted by specific users:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/spaces/by/creator_ids?\
  user_ids=2244994945,783214&\
  space.fields=title,state,scheduled_start" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get Spaces by creator
  response = client.spaces.get_by_creator_ids(
      user_ids=["2244994945", "783214"],
      space_fields=["title", "state", "scheduled_start"]
  )

  for space in response.data:
      print(f"{space.title} - {space.state}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get Spaces by creator
  const response = await client.spaces.getByCreatorIds({
    userIds: ["2244994945", "783214"],
    spaceFields: ["title", "state", "scheduled_start"],
  });

  response.data?.forEach((space) => {
    console.log(`${space.title} - ${space.state}`);
  });
  ```
</CodeGroup>

***

## Include host information

Expand host user data:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/spaces/1DXxyRYNejbKM?\
  space.fields=title,host_ids,state&\
  expansions=host_ids&\
  user.fields=username,verified" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get Space with host info
  response = client.spaces.get(
      "1DXxyRYNejbKM",
      space_fields=["title", "host_ids", "state"],
      expansions=["host_ids"],
      user_fields=["username", "verified"]
  )

  print(f"Space: {response.data.title}")
  # Host info is in response.includes.users
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get Space with host info
  const response = await client.spaces.get("1DXxyRYNejbKM", {
    spaceFields: ["title", "host_ids", "state"],
    expansions: ["host_ids"],
    userFields: ["username", "verified"],
  });

  console.log(`Space: ${response.data?.title}`);
  // Host info is in response.includes?.users
  ```
</CodeGroup>

### Response with expansion

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "id": "1DXxyRYNejbKM",
    "state": "live",
    "title": "Discussing AI and the Future",
    "host_ids": ["2244994945"]
  },
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "username": "XDevelopers",
        "verified": true
      }
    ]
  }
}
```

***

## Space states

| State       | Description          |
| :---------- | :------------------- |
| `live`      | Currently active     |
| `scheduled` | Scheduled for future |
| `ended`     | Has ended            |

***

## Available fields

| Field               | Description               |
| :------------------ | :------------------------ |
| `title`             | Space title               |
| `host_ids`          | Host user IDs             |
| `speaker_ids`       | Speaker user IDs          |
| `participant_count` | Current participants      |
| `scheduled_start`   | Scheduled start time      |
| `started_at`        | Actual start time         |
| `ended_at`          | End time                  |
| `is_ticketed`       | Whether Space has tickets |
| `state`             | Current state             |

***

## Next steps

<CardGroup>
  <Card title="Search Spaces" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834" href="/x-api/spaces/search/quickstart">
    Find Spaces by keyword
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/spaces/space-lookup-by-space-id">
    Full endpoint documentation
  </Card>
</CardGroup>


# Search Spaces
Source: https://docs.x.com/x-api/spaces/search-spaces

get /2/spaces/search
Retrieves a list of Spaces matching the specified search query.



# Spaces Search
Source: https://docs.x.com/x-api/spaces/search/introduction

The Spaces Search endpoint lets you search for live or scheduled Spaces by keyword. Reference for the X API v2 standard tier covering search.

The Spaces Search endpoint lets you search for live or scheduled Spaces by keyword. Find Spaces about topics of interest.

## Overview

<CardGroup>
  <Card title="Keyword search" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834">
    Search Spaces by title
  </Card>

  <Card title="Discover Spaces" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-microphone.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=84616ff8f3d942047a71ee5e0a5adab9">
    Find live and upcoming Spaces
  </Card>
</CardGroup>

***

## Endpoint

| Method | Endpoint                                          | Description       |
| :----- | :------------------------------------------------ | :---------------- |
| GET    | [`/2/spaces/search`](/x-api/spaces/search-spaces) | Search for Spaces |

***

## Parameters

| Parameter      | Description                     |
| :------------- | :------------------------------ |
| `query`        | Search query (required)         |
| `state`        | Filter by `live` or `scheduled` |
| `space.fields` | Additional Space fields         |
| `expansions`   | Related objects to include      |

***

## Example request

```bash theme={null}
curl "https://api.x.com/2/spaces/search?\
query=AI&\
state=live&\
space.fields=title,host_ids,participant_count" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

## Example response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "1DXxyRYNejbKM",
      "state": "live",
      "title": "Discussing AI and the Future",
      "host_ids": ["1234567890"],
      "participant_count": 245
    }
  ],
  "meta": {
    "result_count": 1
  }
}
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/spaces/search/quickstart">
    Search for your first Space
  </Card>

  <Card title="Spaces lookup" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-microphone.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=84616ff8f3d942047a71ee5e0a5adab9" href="/x-api/spaces/lookup/introduction">
    Look up Spaces by ID
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/spaces/search-spaces">
    Full endpoint documentation
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.x.com/x-api/spaces/search/quickstart

Quickstart guide for searching X Spaces by keyword with the X API v2 standard tier Spaces search endpoint, covering authentication and example calls.

This guide walks you through searching for Spaces by keyword.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token
</Note>

***

## Search for Spaces

Search for Spaces matching a keyword:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/spaces/search?\
  query=AI&\
  space.fields=title,host_ids,participant_count,state&\
  state=live" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Search for Spaces
  response = client.spaces.search(
      query="AI",
      space_fields=["title", "host_ids", "participant_count", "state"],
      state="live"
  )

  for space in response.data:
      print(f"{space.title} - {space.participant_count} participants")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Search for Spaces
  const response = await client.spaces.search({
    query: "AI",
    spaceFields: ["title", "host_ids", "participant_count", "state"],
    state: "live",
  });

  response.data?.forEach((space) => {
    console.log(`${space.title} - ${space.participant_count} participants`);
  });
  ```
</CodeGroup>

### Response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "1DXxyRYNejbKM",
      "state": "live",
      "title": "Discussing AI and the Future",
      "host_ids": ["2244994945"],
      "participant_count": 245
    },
    {
      "id": "1YqJDqWYNQDGW",
      "state": "live",
      "title": "AI in Healthcare",
      "host_ids": ["783214"],
      "participant_count": 89
    }
  ],
  "meta": {
    "result_count": 2
  }
}
```

***

## Filter by state

Search only live or scheduled Spaces:

### Live Spaces only

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/spaces/search?query=tech&state=live" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Search live Spaces only
  response = client.spaces.search(query="tech", state="live")

  for space in response.data:
      print(f"LIVE: {space.title}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Search live Spaces only
  const response = await client.spaces.search({
    query: "tech",
    state: "live",
  });

  response.data?.forEach((space) => {
    console.log(`LIVE: ${space.title}`);
  });
  ```
</CodeGroup>

### Scheduled Spaces only

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/spaces/search?query=tech&state=scheduled" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Search scheduled Spaces only
  response = client.spaces.search(query="tech", state="scheduled")

  for space in response.data:
      print(f"SCHEDULED: {space.title}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Search scheduled Spaces only
  const response = await client.spaces.search({
    query: "tech",
    state: "scheduled",
  });

  response.data?.forEach((space) => {
    console.log(`SCHEDULED: ${space.title}`);
  });
  ```
</CodeGroup>

***

## Include host information

Expand host user data:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/spaces/search?\
  query=AI&\
  space.fields=title,host_ids,state&\
  expansions=host_ids&\
  user.fields=username,verified" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Search with host info
  response = client.spaces.search(
      query="AI",
      space_fields=["title", "host_ids", "state"],
      expansions=["host_ids"],
      user_fields=["username", "verified"]
  )

  for space in response.data:
      print(f"{space.title}")
  # Host info is in response.includes.users
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Search with host info
  const response = await client.spaces.search({
    query: "AI",
    spaceFields: ["title", "host_ids", "state"],
    expansions: ["host_ids"],
    userFields: ["username", "verified"],
  });

  response.data?.forEach((space) => {
    console.log(space.title);
  });
  // Host info is in response.includes?.users
  ```
</CodeGroup>

***

## Common parameters

| Parameter      | Description                           |
| :------------- | :------------------------------------ |
| `query`        | Search query (required)               |
| `state`        | Filter: `live`, `scheduled`, or `all` |
| `max_results`  | Results to return (1-100)             |
| `space.fields` | Space fields to include               |
| `expansions`   | Related objects to include            |
| `user.fields`  | User fields to include                |

***

## Next steps

<CardGroup>
  <Card title="Space lookup" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-microphone.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=84616ff8f3d942047a71ee5e0a5adab9" href="/x-api/spaces/lookup/quickstart">
    Look up Spaces by ID
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/spaces/search-spaces">
    Full endpoint documentation
  </Card>
</CardGroup>


# Activity Stream
Source: https://docs.x.com/x-api/stream/activity-stream

get /2/activity/stream
Stream of X Activities



# Get filtered-stream rules
Source: https://docs.x.com/x-api/stream/get-filtered-stream-rules

get /2/tweets/search/stream/rules
Returns the active filtered-stream rules for the authenticated app. Provide `ids` to fetch specific rules; omit it to list all rules.



# Get Rule Counts
Source: https://docs.x.com/x-api/stream/get-rule-counts

get /2/tweets/search/stream/rules/counts



# Get Rule Counts
Source: https://docs.x.com/x-api/stream/get-stream-rule-counts

get /2/tweets/search/stream/rules/counts



# Get filtered-stream rules
Source: https://docs.x.com/x-api/stream/get-stream-rules

get /2/tweets/search/stream/rules
Returns the active filtered-stream rules for the authenticated app. Provide `ids` to fetch specific rules; omit it to list all rules.



# Likes Streams
Source: https://docs.x.com/x-api/stream/likes-streams-introduction

The Likes Streams endpoints deliver real-time like events through persistent HTTP GET connections. Reference for the X API v2 standard tier covering stream.

The Likes Streams endpoints deliver real-time like events through persistent HTTP GET connections. These streams provide access to like activity across X, enabling you to track engagement patterns, monitor content performance, and analyze liking behavior at scale.

Two streams are available:

* **All Likes stream** — Delivers all public like events in real time (firehose).
* **Sampled Likes stream** — Delivers a 10% sample of public like events.

These streaming endpoints use [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0) authentication.

*To use these APIs, you must first set up an account with our enterprise sales team.*

<Note>
  **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).
</Note>

***

## Endpoints

| Method | Endpoint                                                         | Description                         |
| :----- | :--------------------------------------------------------------- | :---------------------------------- |
| GET    | [`/2/likes/firehose/stream`](/x-api/stream/stream-all-likes)     | Stream all like events in real time |
| GET    | [`/2/likes/sample10/stream`](/x-api/stream/stream-sampled-likes) | Stream a 10% sample of like events  |

***

## Streaming fundamentals

<CardGroup>
  <Card title="Consuming streaming data" icon="stream" href="/x-api/fundamentals/consuming-streaming-data">
    Best practices for streaming clients
  </Card>

  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Reconnect gracefully
  </Card>

  <Card title="High volume capacity" icon="gauge-high" href="/x-api/fundamentals/high-volume-capacity">
    Handle high throughput
  </Card>

  <Card title="Recovery and redundancy" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055" href="/x-api/fundamentals/recovery-and-redundancy">
    Build resilient applications
  </Card>
</CardGroup>


# Stream 10% sampled Posts
Source: https://docs.x.com/x-api/stream/stream-10-sampled-posts

get /2/tweets/sample10/stream
Streams a 10% sample of public Posts in real-time.



# Stream all Likes
Source: https://docs.x.com/x-api/stream/stream-all-likes

get /2/likes/firehose/stream
Streams all public Likes in real-time.



# Stream all Posts
Source: https://docs.x.com/x-api/stream/stream-all-posts

get /2/tweets/firehose/stream
Streams all public Posts in real-time.



# Stream English Posts
Source: https://docs.x.com/x-api/stream/stream-english-posts

get /2/tweets/firehose/stream/lang/en
Streams all public English-language Posts in real-time.



# Stream filtered Posts
Source: https://docs.x.com/x-api/stream/stream-filtered-posts

get /2/tweets/search/stream
Streams Posts in real-time matching the active rule set.



# Stream Japanese Posts
Source: https://docs.x.com/x-api/stream/stream-japanese-posts

get /2/tweets/firehose/stream/lang/ja
Streams all public Japanese-language Posts in real-time.



# Stream Korean Posts
Source: https://docs.x.com/x-api/stream/stream-korean-posts

get /2/tweets/firehose/stream/lang/ko
Streams all public Korean-language Posts in real-time.



# Stream Likes compliance data
Source: https://docs.x.com/x-api/stream/stream-likes-compliance-data

get /2/likes/compliance/stream
Streams all compliance data related to Likes for Users.



# Stream Portuguese Posts
Source: https://docs.x.com/x-api/stream/stream-portuguese-posts

get /2/tweets/firehose/stream/lang/pt
Streams all public Portuguese-language Posts in real-time.



# Stream Post labels
Source: https://docs.x.com/x-api/stream/stream-post-labels

get /2/tweets/label/stream
Streams all labeling events applied to Posts.



# Stream Posts compliance data
Source: https://docs.x.com/x-api/stream/stream-posts-compliance-data

get /2/tweets/compliance/stream
Streams all compliance data related to Posts.



# Stream sampled Likes
Source: https://docs.x.com/x-api/stream/stream-sampled-likes

get /2/likes/sample10/stream
Streams a 10% sample of public Likes in real-time.



# Stream sampled Posts
Source: https://docs.x.com/x-api/stream/stream-sampled-posts

get /2/tweets/sample/stream
Streams a 1% sample of public Posts in real-time.



# Stream Users compliance data
Source: https://docs.x.com/x-api/stream/stream-users-compliance-data

get /2/users/compliance/stream
Streams all compliance data related to Users.



# Update stream rules
Source: https://docs.x.com/x-api/stream/update-stream-rules

post /2/tweets/search/stream/rules
Adds or deletes rules from the active rule set for the filtered stream. Exactly one of `add`, `delete`, or `?delete_all=true` must be specified. Use `?dry_run=true` to validate without committing.



# Get AI trend by ID
Source: https://docs.x.com/x-api/trends/get-ai-trends-by-id

get /2/ai_trends/{id}
Retrieve a single AI-curated trend by its identifier, including metadata about the trend and the Posts driving it, via the X API v2.



# Get Trends Personalized Trends
Source: https://docs.x.com/x-api/trends/get-personalized-trends

get /2/users/personalized_trends



# Get Trends by Woeid
Source: https://docs.x.com/x-api/trends/get-trends-by-woeid

get /2/trends/by/woeid/{woeid}



# Get Trends Personalized Trends
Source: https://docs.x.com/x-api/trends/get-trends-personalized-trends

get /2/users/personalized_trends



# Personalized Trends
Source: https://docs.x.com/x-api/trends/personalized-trends/introduction

The X API v2 Personalized Trends endpoint returns trending topics tailored to the authenticated user based on their location, interests, and account activity.

The Personalized Trends endpoint returns trending topics tailored to the authenticated user, based on their location and interests.

## Overview

<CardGroup>
  <Card title="Personalized" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305">
    Trends tailored to the user
  </Card>

  <Card title="Location-aware" icon="location-dot">
    Based on user's location
  </Card>

  <Card title="Real-time" icon="bolt">
    Current trending topics
  </Card>
</CardGroup>

***

## Endpoint

| Method | Endpoint                       | Description             |
| :----- | :----------------------------- | :---------------------- |
| GET    | `/2/users/personalized_trends` | Get personalized trends |

***

## Example request

```bash theme={null}
curl "https://api.x.com/2/users/personalized_trends" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
```

## Example response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "trend_name": "#AI",
      "tweet_count": 125000
    },
    {
      "trend_name": "Machine Learning",
      "tweet_count": 85000
    }
  ]
}
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * User Access Tokens via [OAuth 2.0 PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2)
  * Premium User Subscription
</Note>

<CardGroup>
  <Card title="Trends by WOEID" icon="globe" href="/x-api/trends/trends-by-woeid/introduction">
    Get trends for a specific location
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/trends/personalized-trends">
    Full endpoint documentation
  </Card>
</CardGroup>


# Trends by WOEID
Source: https://docs.x.com/x-api/trends/trends-by-woeid/introduction

The Trends by WOEID endpoint returns trending topics for a specific geographic location. Reference for the X API v2 standard tier covering trends by woeid.

The Trends by WOEID endpoint returns trending topics for a specific geographic location, identified by a Yahoo! Where On Earth ID (WOEID).

## Overview

<CardGroup>
  <Card title="Location-specific" icon="location-dot">
    Trends for any supported location
  </Card>

  <Card title="Global coverage" icon="globe">
    Countries, cities, and regions
  </Card>

  <Card title="Real-time" icon="bolt">
    Current trending topics
  </Card>
</CardGroup>

***

## Endpoint

| Method | Endpoint                                                      | Description            |
| :----- | :------------------------------------------------------------ | :--------------------- |
| GET    | [`/2/trends/by/woeid/:id`](/x-api/trends/get-trends-by-woeid) | Get trends for a WOEID |

***

## Common WOEIDs

| Location       | WOEID    |
| :------------- | :------- |
| Worldwide      | 1        |
| United States  | 23424977 |
| United Kingdom | 23424975 |
| Japan          | 23424856 |
| New York       | 2459115  |
| Los Angeles    | 2442047  |
| London         | 44418    |
| Tokyo          | 1118370  |

***

## Example request

```bash theme={null}
curl "https://api.x.com/2/trends/by/woeid/1" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

## Example response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "trend_name": "#AI"
    },
    {
      "trend_name": "Breaking News"
    }
  ]
}
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [Bearer Token](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Personalized trends" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305" href="/x-api/trends/personalized-trends/introduction">
    Get trends for the authenticated user
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/trends/trends-by-woeid">
    Full endpoint documentation
  </Card>
</CardGroup>


# Get Usage
Source: https://docs.x.com/x-api/usage/get-usage

get /2/usage/tweets



# Usage
Source: https://docs.x.com/x-api/usage/introduction

The Usage endpoint lets you monitor your API usage, including the number of Posts consumed. Reference for the X API v2 standard tier covering usage.

The Usage endpoint lets you monitor your API usage, including the number of Posts consumed. Track your usage programmatically to manage costs and stay within limits.

<Note>
  Pay-per-usage plans are subject to a monthly cap of 3 million Post reads. If you need higher volume, consider an [Enterprise plan](/forms/enterprise-api-interest).
</Note>

## Overview

<CardGroup>
  <Card title="Post usage" icon="chart-simple">
    Track Posts consumed
  </Card>

  <Card title="Daily breakdown" icon="calendar-days">
    View usage by day
  </Card>

  <Card title="App-level" icon="gauge">
    Monitor usage across your App
  </Card>
</CardGroup>

***

## Endpoint

| Method | Endpoint                                    | Description         |
| :----- | :------------------------------------------ | :------------------ |
| GET    | [`/2/usage/tweets`](/x-api/usage/get-usage) | Get Post usage data |

***

## Response data

The response includes daily Post consumption counts:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "daily_project_usage": [
      {
        "date": "2024-01-15",
        "usage": [
          {
            "app_id": "12345678",
            "tweets_consumed": 15420
          }
        ]
      }
    ],
    "project_id": "1234567890",
    "project_cap": 10000000
  }
}
```

### Fields

| Field                 | Description               |
| :-------------------- | :------------------------ |
| `daily_project_usage` | Array of daily usage data |
| `date`                | Date in YYYY-MM-DD format |
| `app_id`              | Your App's ID             |
| `tweets_consumed`     | Posts consumed that day   |
| `project_cap`         | Your monthly Post limit   |

***

## Example request

```bash theme={null}
curl "https://api.x.com/2/usage/tweets" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

***

## Use cases

* **Cost monitoring** — Track consumption against your budget
* **Alerting** — Set up alerts when approaching limits
* **Optimization** — Identify high-consumption endpoints
* **Reporting** — Generate usage reports

<Tip>
  Resources are deduplicated within a 24-hour UTC window, so requesting the same resource multiple times in a day only counts as one charge. [Learn more about pricing →](/x-api/getting-started/pricing)
</Tip>

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [Bearer Token](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/usage/post-usage">
    Full endpoint documentation
  </Card>

  <Card title="Developer Console" icon="gauge" href="https://developer.x.com/en/portal/dashboard">
    View usage in the dashboard
  </Card>
</CardGroup>


# Block Users Dms
Source: https://docs.x.com/x-api/users/block-dms

post /2/users/{id}/dm/block



# Block Users Dms
Source: https://docs.x.com/x-api/users/block-users-dms

post /2/users/{id}/dm/block



# Integration Guide
Source: https://docs.x.com/x-api/users/blocks/integrate

This guide covers the key concepts you need to integrate the blocks endpoints into your. Reference for the X API v2 standard tier covering blocks.

This guide covers the key concepts you need to integrate the blocks endpoints into your application.

<Callout icon="/icons/xds/icon-key.svg">
  The block and unblock users endpoints are only available under the Enterprise plan. You can fill out the Enterprise interest form [here](/forms/enterprise-api-interest).
</Callout>

***

## Authentication

Blocks 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 for new applications |
| [OAuth 1.0a User Context](/resources/fundamentals/authentication)                                                              | Legacy support                   |

<Warning>
  App-Only authentication is not supported. You must authenticate on behalf of a user.
</Warning>

### Required scopes (OAuth 2.0)

| Scope         | Required for                     |
| :------------ | :------------------------------- |
| `block.read`  | Retrieving blocked accounts      |
| `block.write` | Blocking and unblocking accounts |
| `users.read`  | Required with block scopes       |

***

## Endpoints overview

| Method | Endpoint                                            | Description                  | Availability                                                   |
| :----- | :-------------------------------------------------- | :--------------------------- | :------------------------------------------------------------- |
| GET    | `/2/users/:id/blocking`                             | Get list of blocked accounts | <div><Badge>Pay-per-use</Badge><Badge>Enterprise</Badge></div> |
| POST   | `/2/users/:id/blocking`                             | Block an account             | <Badge>Enterprise</Badge>                                      |
| DELETE | `/2/users/:source_user_id/blocking/:target_user_id` | Unblock an account           | <Badge>Enterprise</Badge>                                      |

***

## Fields and expansions

### Default response

```json theme={null}
{
  "data": [
    {
      "id": "1234567890",
      "name": "Example User",
      "username": "example"
    }
  ]
}
```

### Available fields

<Accordion title="user.fields">
  | Field               | Description               |
  | :------------------ | :------------------------ |
  | `created_at`        | Account creation date     |
  | `description`       | User bio                  |
  | `profile_image_url` | Avatar URL                |
  | `public_metrics`    | Follower/following counts |
  | `verified`          | Verification status       |
</Accordion>

<Accordion title="expansions">
  | Expansion         | Description        |
  | :---------------- | :----------------- |
  | `pinned_tweet_id` | User's pinned Post |
</Accordion>

***

## What happens when you block

<CardGroup>
  <Card title="They can't" icon="xmark">
    * See your Posts (unless logged out)
    * Follow you
    * Send you DMs
    * Add you to Lists
    * Tag you in photos
  </Card>

  <Card title="You can't" icon="xmark">
    * See their Posts
    * Follow them
    * Send them DMs
  </Card>
</CardGroup>

<Note>
  When you block someone who follows you, they are automatically unfollowed.
</Note>

***

## Pagination

For users with large block lists, results are paginated:

<CodeGroup>
  ```bash cURL theme={null}
  # First request
  curl "https://api.x.com/2/users/123/blocking?max_results=100" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"

  # Subsequent request with pagination token
  curl "https://api.x.com/2/users/123/blocking?max_results=100&pagination_token=NEXT_TOKEN" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  # Use OAuth 2.0 user access token
  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # The SDK handles pagination automatically
  all_blocked = []

  for page in client.users.get_blocking(user_id="123", max_results=100):
      if page.data:
          all_blocked.extend(page.data)

  print(f"Blocked {len(all_blocked)} users")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  async function getAllBlockedUsers(userId) {
    const allBlocked = [];

    // The SDK handles pagination automatically
    const paginator = client.users.getBlocking(userId, { maxResults: 100 });

    for await (const page of paginator) {
      if (page.data) {
        allBlocked.push(...page.data);
      }
    }

    return allBlocked;
  }

  // Usage
  const blocked = await getAllBlockedUsers("123");
  console.log(`Blocked ${blocked.length} users`);
  ```
</CodeGroup>

***

## Error handling

| Status | Error             | Solution                                                                                         |
| :----- | :---------------- | :----------------------------------------------------------------------------------------------- |
| 400    | Invalid request   | Check user ID format                                                                             |
| 401    | Unauthorized      | Verify access token                                                                              |
| 403    | Forbidden         | Check scopes and permissions. Block/unblock require [Enterprise](/forms/enterprise-api-interest) |
| 404    | Not Found         | User doesn't exist                                                                               |
| 429    | Too Many Requests | Wait and retry                                                                                   |

***

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/users/blocks/quickstart">
    Make your first blocks request
  </Card>

  <Card title="Mutes" icon="volume-xmark" href="/x-api/users/mutes/introduction">
    Mute users instead of blocking
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-blocking">
    Full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# Blocks
Source: https://docs.x.com/x-api/users/blocks/introduction

The Blocks endpoints let you retrieve the list of users blocked by the authenticated user, as well. Reference for the X API v2 standard tier covering blocks.

The Blocks endpoints let you retrieve the list of users blocked by the authenticated user, as well as block and unblock users.

<Callout icon="/icons/xds/icon-key.svg">
  The block and unblock users endpoints are only available under the Enterprise plan. You can fill out the Enterprise interest form [here](/forms/enterprise-api-interest).
</Callout>

## Overview

<CardGroup>
  <Card title="Blocked users" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5">
    Get your blocked user list
  </Card>

  <Card title="Block" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-block.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=702a65b4001948aebcc42635b8e2eac7">
    Block a user
  </Card>

  <Card title="Unblock" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-checkmark-circle.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=bd3e78cd745fde73a934535acacaff59">
    Unblock a user
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                             | Description       | Availability                                                   |
| :----- | :--------------------------------------------------- | :---------------- | :------------------------------------------------------------- |
| GET    | [`/2/users/:id/blocking`](/x-api/users/get-blocking) | Get blocked users | <div><Badge>Pay-per-use</Badge><Badge>Enterprise</Badge></div> |
| POST   | `/2/users/:id/blocking`                              | Block a user      | <Badge>Enterprise</Badge>                                      |
| DELETE | `/2/users/:source_user_id/blocking/:target_user_id`  | Unblock a user    | <Badge>Enterprise</Badge>                                      |

***

## Example: Get blocked users

```bash theme={null}
curl "https://api.x.com/2/users/123456789/blocking?\
user.fields=username,description" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
```

## Example: Block a user (Enterprise only)

```bash theme={null}
curl -X POST "https://api.x.com/2/users/123456789/blocking" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_user_id": "9876543210"}'
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * User Access Tokens via [OAuth 2.0 PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/users/blocks/quickstart">
    Get started with blocks
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/users/blocks/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-blocking">
    Full endpoint documentation
  </Card>
</CardGroup>


# Migration guide
Source: https://docs.x.com/x-api/users/blocks/migrate

The block and unblock users endpoints are only available under the Enterprise plan. Reference for the X API v2 standard tier covering blocks.

<Callout icon="/icons/xds/icon-key.svg">
  The block and unblock users endpoints are only available under the Enterprise plan. You can fill out the Enterprise interest form [here](/forms/enterprise-api-interest).
</Callout>

### Blocks lookup: Standard v1.1 compared to X API v2

If you have been working with the standard v1.1 [GET blocks/ids](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-blocks-ids) and [GET blocks/list](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-blocks-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 blocks 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 blocks 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 blocks 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/blocks/ids.json](https://api.x.com/1.1/blocks/ids.json)
    (list of user IDs who are blocked by the specified user)
  * GET [https://api.x.com/1.1/blocks/lists.json](https://api.x.com/1.1/blocks/lists.json)
    (list of users who are blocked by the specified user)
* X API v2 endpoint:
  * GET [https://api.x.com/2/users/:id/blocking](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 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 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/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 [P](/x-api/fundamentals/data-dictionary/reference#tweet)ost 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. 
* 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/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
* 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)

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/123456789/blocking?user.fields=username,verified&max_results=100" \
    -H "Authorization: OAuth ..."
  ```

  ```python title="Python" lines wrap icon="python" theme={null}
  # 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 title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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}`);
    });
  }
  ```
</CodeGroup>

### Block a user (v2) — Enterprise only

<CodeGroup>
  ```bash cURL theme={null}
  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 title="Python" lines wrap icon="python" theme={null}
  # 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 title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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}`);
  ```
</CodeGroup>


# Quickstart
Source: https://docs.x.com/x-api/users/blocks/quickstart

This guide walks you through retrieving your block list, as well as blocking and unblocking users. Reference for the X API v2 standard tier covering blocks.

This guide walks you through retrieving your block list, as well as blocking and unblocking users.

<Callout icon="/icons/xds/icon-key.svg">
  The block and unblock users endpoints are only available under the Enterprise plan. You can fill out the Enterprise interest form [here](/forms/enterprise-api-interest).
</Callout>

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Get blocked users

<Steps>
  <Step title="Get your user ID">
    You need your authenticated user's ID to retrieve your block list. You can get it from the `/2/users/me` endpoint or use the ID from your tokens.
  </Step>

  <Step title="Request your block list">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/users/123456789/blocking?\
      user.fields=username,verified,created_at&\
      max_results=100" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

      # Get blocked users with pagination
      for page in client.users.get_blocking(
          "123456789",
          user_fields=["username", "verified", "created_at"],
          max_results=100
      ):
          for user in page.data:
              print(f"{user.username} - Created: {user.created_at}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

      // Get blocked users with pagination
      const paginator = client.users.getBlocking("123456789", {
        userFields: ["username", "verified", "created_at"],
        maxResults: 100,
      });

      for await (const page of paginator) {
        page.data?.forEach((user) => {
          console.log(`${user.username} - Created: ${user.created_at}`);
        });
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": [
        {
          "id": "17874544",
          "name": "Example User",
          "username": "example_user",
          "verified": false,
          "created_at": "2008-12-04T18:51:57.000Z"
        }
      ],
      "meta": {
        "result_count": 1,
        "next_token": "abc123"
      }
    }
    ```
  </Step>
</Steps>

***

## Block a user (Enterprise only)

<Steps>
  <Step title="Identify the target user">
    Get the user ID of the account you want to block.
  </Step>

  <Step title="Send a block request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/users/123456789/blocking" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"target_user_id": "9876543210"}'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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="9876543210"
      )
      print(f"Blocking: {response.data.blocking}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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: "9876543210",
      });
      console.log(`Blocking: ${response.data?.blocking}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Confirm the block">
    ```json theme={null}
    {
      "data": {
        "blocking": true
      }
    }
    ```
  </Step>
</Steps>

***

## Unblock a user (Enterprise only)

<Steps>
  <Step title="Send an unblock request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X DELETE "https://api.x.com/2/users/123456789/blocking/9876543210" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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)

      # Unblock a user
      response = client.users.unblock(
          source_user_id="123456789",
          target_user_id="9876543210"
      )
      print(f"Blocking: {response.data.blocking}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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 });

      // Unblock a user
      const response = await client.users.unblock("123456789", "9876543210");
      console.log(`Blocking: ${response.data?.blocking}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Confirm the unblock">
    ```json theme={null}
    {
      "data": {
        "blocking": false
      }
    }
    ```
  </Step>
</Steps>

***

## Next steps

<CardGroup>
  <Card title="Mutes" icon="volume-xmark" href="/x-api/users/mutes/introduction">
    Mute users instead of blocking
  </Card>

  <Card title="Follows" icon="user-plus" href="/x-api/users/follows/introduction">
    Manage follows
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/users/blocks/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-blocking">
    Full endpoint documentation
  </Card>
</CardGroup>


# Create Users Bookmark
Source: https://docs.x.com/x-api/users/create-bookmark

post /2/users/{id}/bookmarks



# Create Bookmark Folder
Source: https://docs.x.com/x-api/users/create-bookmark-folder

post /2/users/{id}/bookmarks/folders
Creates a new Bookmark folder for the authenticated user.



# Create Users Bookmark
Source: https://docs.x.com/x-api/users/create-users-bookmark

post /2/users/{id}/bookmarks



# Delete Bookmark
Source: https://docs.x.com/x-api/users/delete-bookmark

delete /2/users/{id}/bookmarks/{tweet_id}
Removes a Post from the authenticated user's Bookmarks by its ID.



# Follow List
Source: https://docs.x.com/x-api/users/follow-list

post /2/users/{id}/followed_lists



# Follow User
Source: https://docs.x.com/x-api/users/follow-user

post /2/users/{id}/following



# Follows
Source: https://docs.x.com/x-api/users/follows/introduction

The Follows endpoints let you follow and unfollow users, and retrieve follower and following. Reference for the X API v2 standard tier covering follows.

The Follows endpoints let you follow and unfollow users, and retrieve follower and following lists for any user.

## Overview

<CardGroup>
  <Card title="Follow" icon="user-plus">
    Follow a user on behalf of the authenticated user
  </Card>

  <Card title="Unfollow" icon="user-minus">
    Unfollow a user
  </Card>

  <Card title="Followers" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980">
    Get a user's followers
  </Card>

  <Card title="Following" icon="user-group">
    Get who a user follows
  </Card>
</CardGroup>

***

## Endpoints

### Follows lookup

| Method | Endpoint                                               | Description            |
| :----- | :----------------------------------------------------- | :--------------------- |
| GET    | [`/2/users/:id/followers`](/x-api/users/get-followers) | Get a user's followers |
| GET    | [`/2/users/:id/following`](/x-api/users/get-following) | Get who a user follows |

### Manage follows

| Method | Endpoint                                                                           | Description     |
| :----- | :--------------------------------------------------------------------------------- | :-------------- |
| POST   | [`/2/users/:id/following`](/x-api/users/follow-user)                               | Follow a user   |
| DELETE | [`/2/users/:source_user_id/following/:target_user_id`](/x-api/users/unfollow-user) | Unfollow a user |

***

## Example: Get followers

```bash theme={null}
curl "https://api.x.com/2/users/2244994945/followers?\
user.fields=username,verified,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

## Example: Follow a user

```bash theme={null}
curl -X POST "https://api.x.com/2/users/123456789/following" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_user_id": "2244994945"}'
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/users/follows/quickstart">
    Get started with follows
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-followers">
    Full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# Follows endpoints migration overview
Source: https://docs.x.com/x-api/users/follows/migrate/overview

Migrate followers, following, and follow management from Standard v1.1 friendships endpoints to the X API v2 follows endpoints with mapped parameters.

## 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<br /><br />/1.1/friends/list.json<br /><br />/1.1/followers/ids.json<br /><br />/1.1/followers/list.json                                                               | /2/users/:id/following<br /><br />/2/users/:id/followers                                                                                                                                                                                                                                                                                              |
| [Authentication](/resources/fundamentals/authentication)                                                                                                           | OAuth 1.0a User Context<br /><br />App only                                                                                                                                                  | OAuth 1.0a User Context<br /><br />OAuth 2.0 Authorization Code with PKCE<br /><br />App only                                                                                                                                                                                                                                                         |
| Default request [rate limits](/resources/fundamentals/rate-limits)                                                                                                 | 15 requests per 15 min (per user)<br /><br />15 requests per 15 min (per app)                                                                                                                | 15 requests per 15 min (per user)<br /><br />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.<br /><br />  <br /><br />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.<br /><br />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)<br /><br />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) | [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<br /><br />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) | [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<br /><br />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)


# v1 to v2
Source: https://docs.x.com/x-api/users/follows/migrate/standard-to-twitter-api-v2

If you have been working with the standard v1.1 POST friendships/create and POST. Reference for the X API v2 standard tier covering migrate.

#### 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](https://api.x.com/1.1/friendships/create.json)
    (follow a user)
  * POST [https://api.x.com/1.1/friendships/destroy.json](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](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](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.


# Quickstart
Source: https://docs.x.com/x-api/users/follows/quickstart

This guide walks you through retrieving followers and following lists, and managing follows. Reference for the X API v2 standard tier covering follows.

This guide walks you through retrieving followers and following lists, and managing follows.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token (for lookups)
  * User Access Token (for managing follows)
</Note>

***

## Get a user's followers

Retrieve the list of users following a specific user:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/2244994945/followers?\
  user.fields=username,verified,public_metrics&\
  max_results=100" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get a user's followers with pagination
  for page in client.users.get_followers(
      "2244994945",
      user_fields=["username", "verified", "public_metrics"],
      max_results=100
  ):
      for user in page.data:
          print(f"{user.username} - Followers: {user.public_metrics.followers_count}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get a user's followers with pagination
  const paginator = client.users.getFollowers("2244994945", {
    userFields: ["username", "verified", "public_metrics"],
    maxResults: 100,
  });

  for await (const page of paginator) {
    page.data?.forEach((user) => {
      console.log(`${user.username} - Followers: ${user.public_metrics?.followers_count}`);
    });
  }
  ```
</CodeGroup>

### Response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "1234567890",
      "name": "Developer",
      "username": "dev_user",
      "verified": false,
      "public_metrics": {
        "followers_count": 500,
        "following_count": 200,
        "tweet_count": 1500
      }
    }
  ],
  "meta": {
    "result_count": 1,
    "next_token": "abc123"
  }
}
```

***

## Get who a user follows

Retrieve the list of users that a specific user follows:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/2244994945/following?\
  user.fields=username,verified&\
  max_results=100" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get users that a user follows
  for page in client.users.get_following(
      "2244994945",
      user_fields=["username", "verified"],
      max_results=100
  ):
      for user in page.data:
          print(f"{user.username} - Verified: {user.verified}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get users that a user follows
  const paginator = client.users.getFollowing("2244994945", {
    userFields: ["username", "verified"],
    maxResults: 100,
  });

  for await (const page of paginator) {
    page.data?.forEach((user) => {
      console.log(`${user.username} - Verified: ${user.verified}`);
    });
  }
  ```
</CodeGroup>

***

## Follow a user

Follow a user on behalf of the authenticated user:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.x.com/2/users/123456789/following" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"target_user_id": "2244994945"}'
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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}`);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": {
    "following": true,
    "pending_follow": false
  }
}
```

<Note>
  If the target account is protected, `pending_follow` will be `true` until the follow request is approved.
</Note>

***

## Unfollow a user

Unfollow a user on behalf of the authenticated user:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.x.com/2/users/123456789/following/2244994945" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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}`);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": {
    "following": false
  }
}
```

***

## Common parameters

| Parameter          | Description                            |
| :----------------- | :------------------------------------- |
| `max_results`      | Results per page (1-1000, default 100) |
| `pagination_token` | Token for next page                    |
| `user.fields`      | Additional user fields                 |
| `expansions`       | Related objects to include             |

***

## Next steps

<CardGroup>
  <Card title="User lookup" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305" href="/x-api/users/lookup/introduction">
    Look up user profiles
  </Card>

  <Card title="Blocks" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-block.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=702a65b4001948aebcc42635b8e2eac7" href="/x-api/users/blocks/introduction">
    Block and unblock users
  </Card>

  <Card title="Mutes" icon="volume-xmark" href="/x-api/users/mutes/introduction">
    Mute and unmute users
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-followers">
    Full endpoint documentation
  </Card>
</CardGroup>


# Get Users Affiliates
Source: https://docs.x.com/x-api/users/get-affiliates

get /2/users/{id}/affiliates



# Get Users Blocking
Source: https://docs.x.com/x-api/users/get-blocking

get /2/users/{id}/blocking



# Get Users Bookmark Folders
Source: https://docs.x.com/x-api/users/get-bookmark-folders

get /2/users/{id}/bookmarks/folders



# Get Users Bookmarks
Source: https://docs.x.com/x-api/users/get-bookmarks

get /2/users/{id}/bookmarks



# Get Users Bookmarks by Folder ID
Source: https://docs.x.com/x-api/users/get-bookmarks-by-folder-id

get /2/users/{id}/bookmarks/folders/{folder_id}



# Get Users Followed Lists
Source: https://docs.x.com/x-api/users/get-followed-lists

get /2/users/{id}/followed_lists



# Get Users Followers
Source: https://docs.x.com/x-api/users/get-followers

get /2/users/{id}/followers



# Get Users Following
Source: https://docs.x.com/x-api/users/get-following

get /2/users/{id}/following



# Get Users Liked Posts
Source: https://docs.x.com/x-api/users/get-liked-posts

get /2/users/{id}/liked_tweets



# Get Users List Memberships
Source: https://docs.x.com/x-api/users/get-list-memberships

get /2/users/{id}/list_memberships



# Get Users Mentions
Source: https://docs.x.com/x-api/users/get-mentions

get /2/users/{id}/mentions
When both are provided, `start_time` must be earlier than `end_time`. When both are provided, `since_id` must be less than `until_id`.



# Get Users Muting
Source: https://docs.x.com/x-api/users/get-muting

get /2/users/{id}/muting



# Get Users Me
Source: https://docs.x.com/x-api/users/get-my-user

get /2/users/me



# Get Users Owned Lists
Source: https://docs.x.com/x-api/users/get-owned-lists

get /2/users/{id}/owned_lists



# Get Users Pinned Lists
Source: https://docs.x.com/x-api/users/get-pinned-lists

get /2/users/{id}/pinned_lists



# Get Users Posts
Source: https://docs.x.com/x-api/users/get-posts

get /2/users/{id}/tweets
When both are provided, `start_time` must be earlier than `end_time`. When both are provided, `since_id` must be less than `until_id`.



# Get public keys
Source: https://docs.x.com/x-api/users/get-public-keys

get /2/users/public_keys
Returns registered public keys for X Chat encryption for the specified users.



# Get public keys
Source: https://docs.x.com/x-api/users/get-public-keys-1

get /2/users/{id}/public_keys
Returns a user's registered public keys for X Chat encryption.



# Get public keys
Source: https://docs.x.com/x-api/users/get-public-keys-for-multiple-users

get /2/users/public_keys
Returns registered public keys for X Chat encryption for the specified users.



# Get Users Reposts of Me
Source: https://docs.x.com/x-api/users/get-reposts-of-me

get /2/users/reposts_of_me



# Get Users Timeline
Source: https://docs.x.com/x-api/users/get-timeline

get /2/users/{id}/timelines/reverse_chronological
When both are provided, `start_time` must be earlier than `end_time`. When both are provided, `since_id` must be less than `until_id`.



# Get Users by ID
Source: https://docs.x.com/x-api/users/get-user-by-id

get /2/users/{id}



# Get Users by Username
Source: https://docs.x.com/x-api/users/get-user-by-username

get /2/users/by/username/{username}



# Get public keys
Source: https://docs.x.com/x-api/users/get-user-public-keys

get /2/users/{id}/public_keys
Returns a user's registered public keys for X Chat encryption.



# Get Users Affiliates
Source: https://docs.x.com/x-api/users/get-users-affiliates

get /2/users/{id}/affiliates



# Get Users Blocking
Source: https://docs.x.com/x-api/users/get-users-blocking

get /2/users/{id}/blocking



# Get Users Bookmark Folders
Source: https://docs.x.com/x-api/users/get-users-bookmark-folders

get /2/users/{id}/bookmarks/folders



# Get Users Bookmarks
Source: https://docs.x.com/x-api/users/get-users-bookmarks

get /2/users/{id}/bookmarks



# Get Users Bookmarks by Folder ID
Source: https://docs.x.com/x-api/users/get-users-bookmarks-by-folder-id

get /2/users/{id}/bookmarks/folders/{folder_id}



# Get Users by ID
Source: https://docs.x.com/x-api/users/get-users-by-id

get /2/users/{id}



# Get Users by IDs
Source: https://docs.x.com/x-api/users/get-users-by-ids

get /2/users



# Get Users by Username
Source: https://docs.x.com/x-api/users/get-users-by-username

get /2/users/by/username/{username}



# Get Users by Usernames
Source: https://docs.x.com/x-api/users/get-users-by-usernames

get /2/users/by



# Get Users Followed Lists
Source: https://docs.x.com/x-api/users/get-users-followed-lists

get /2/users/{id}/followed_lists



# Get Users Followers
Source: https://docs.x.com/x-api/users/get-users-followers

get /2/users/{id}/followers



# Get Users Following
Source: https://docs.x.com/x-api/users/get-users-following

get /2/users/{id}/following



# Get Users Liked Posts
Source: https://docs.x.com/x-api/users/get-users-liked-posts

get /2/users/{id}/liked_tweets



# Get Users List Memberships
Source: https://docs.x.com/x-api/users/get-users-list-memberships

get /2/users/{id}/list_memberships



# Get Users Me
Source: https://docs.x.com/x-api/users/get-users-me

get /2/users/me



# Get Users Mentions
Source: https://docs.x.com/x-api/users/get-users-mentions

get /2/users/{id}/mentions
When both are provided, `start_time` must be earlier than `end_time`. When both are provided, `since_id` must be less than `until_id`.



# Get Users Muting
Source: https://docs.x.com/x-api/users/get-users-muting

get /2/users/{id}/muting



# Get Users Owned Lists
Source: https://docs.x.com/x-api/users/get-users-owned-lists

get /2/users/{id}/owned_lists



# Get Users Pinned Lists
Source: https://docs.x.com/x-api/users/get-users-pinned-lists

get /2/users/{id}/pinned_lists



# Get Users Posts
Source: https://docs.x.com/x-api/users/get-users-posts

get /2/users/{id}/tweets
When both are provided, `start_time` must be earlier than `end_time`. When both are provided, `since_id` must be less than `until_id`.



# Get Users Reposts of Me
Source: https://docs.x.com/x-api/users/get-users-reposts-of-me

get /2/users/reposts_of_me



# Get Users Timeline
Source: https://docs.x.com/x-api/users/get-users-timeline

get /2/users/{id}/timelines/reverse_chronological
When both are provided, `start_time` must be earlier than `end_time`. When both are provided, `since_id` must be less than `until_id`.



# Like Post
Source: https://docs.x.com/x-api/users/like-post

post /2/users/{id}/likes



# Integration Guide
Source: https://docs.x.com/x-api/users/lookup/integrate

This guide covers the key concepts you need to integrate the User lookup endpoints into your. Reference for the X API v2 standard tier covering lookup.

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:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/by/username/XDevelopers" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  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 theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  const response = await client.users.getByUsername("XDevelopers");
  console.log(response.data);
  ```
</CodeGroup>

### User Context authentication

Required for the authenticated user endpoint (`/2/users/me`):

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/me" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python Python SDK theme={null}
  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 theme={null}
  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);
  ```
</CodeGroup>

<Warning>
  The `/2/users/me` endpoint only works with User Context authentication. App-Only tokens will return an error.
</Warning>

***

## 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 theme={null}
{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers"
  }
}
```

### Available fields

<Accordion title="user.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      |
</Accordion>

<Accordion title="tweet.fields (requires pinned_tweet_id expansion)">
  | Field            | Description              |
  | :--------------- | :----------------------- |
  | `created_at`     | Post creation timestamp  |
  | `text`           | Post content             |
  | `public_metrics` | Engagement counts        |
  | `entities`       | Hashtags, mentions, URLs |
</Accordion>

### Example with fields

<CodeGroup>
  ```bash cURL theme={null}
  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 title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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
  ```
</CodeGroup>

### Response with expansions

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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"
      }
    ]
  }
}
```

<Card title="Fields and expansions guide" icon="sliders" href="/x-api/fundamentals/fields">
  Learn more about customizing responses
</Card>

***

## Batch lookups

Look up multiple users in a single request:

<CodeGroup>
  ```bash cURL (by IDs) theme={null}
  curl "https://api.x.com/2/users?ids=2244994945,783214,6253282&\
  user.fields=username,verified" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```bash cURL (by usernames) theme={null}
  curl "https://api.x.com/2/users/by?usernames=XDevelopers,X,XAPI&\
  user.fields=username,verified" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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}`);
  });
  ```
</CodeGroup>

<Tip>
  Batch requests are limited to 100 users. Use multiple requests for larger datasets.
</Tip>

***

## 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 title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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

<CardGroup>
  <Card title="Batch requests" icon="layer-group">
    Use multi-user endpoints to fetch up to 100 users at once, reducing API calls.
  </Card>

  <Card title="Request only needed fields" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e">
    Specify only the fields you need to minimize response size.
  </Card>

  <Card title="Cache user data" icon="database">
    Cache user profiles locally to reduce repeated requests.
  </Card>

  <Card title="Handle errors gracefully" icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca">
    Check for partial errors in batch responses.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-user-by-id">
    Complete endpoint documentation
  </Card>

  <Card title="Data dictionary" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/fundamentals/data-dictionary">
    All available objects and fields
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>

  <Card title="Error handling" icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" href="/x-api/fundamentals/response-codes-and-errors">
    Handle errors gracefully
  </Card>
</CardGroup>


# User Lookup
Source: https://docs.x.com/x-api/users/lookup/introduction

The User lookup endpoints let you retrieve profile information for one or more users. Reference for the X API v2 standard tier covering lookup.

The User lookup endpoints let you retrieve profile information for one or more users. Look up users by their ID, username, or get details for the currently authenticated user.

## Overview

<CardGroup>
  <Card title="By ID" icon="fingerprint">
    Look up users by their unique user ID
  </Card>

  <Card title="By username" icon="at">
    Look up users by their @handle
  </Card>

  <Card title="Multiple users" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980">
    Retrieve up to 100 users per request
  </Card>

  <Card title="Authenticated user" icon="user-check">
    Get details for the current user
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                                              | Description                        |
| :----- | :-------------------------------------------------------------------- | :--------------------------------- |
| GET    | [`/2/users/:id`](/x-api/users/get-user-by-id)                         | Get user by ID                     |
| GET    | [`/2/users`](/x-api/users/get-users-by-ids)                           | Get users by IDs (up to 100)       |
| GET    | [`/2/users/by/username/:username`](/x-api/users/get-user-by-username) | Get user by username               |
| GET    | [`/2/users/by`](/x-api/users/get-users-by-usernames)                  | Get users by usernames (up to 100) |
| GET    | [`/2/users/me`](/x-api/users/get-my-user)                             | Get authenticated user             |

***

## Example request

```bash theme={null}
curl "https://api.x.com/2/users/by/username/XDevelopers?\
user.fields=created_at,description,public_metrics,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

## Example response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "description": "The voice of the X developer community",
    "verified": true,
    "public_metrics": {
      "followers_count": 583423,
      "following_count": 2048,
      "tweet_count": 14052,
      "listed_count": 1672
    }
  }
}
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="User lookup quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/users/lookup/quickstart/user-lookup">
    Look up users by ID or username
  </Card>

  <Card title="Authenticated user quickstart" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305" href="/x-api/users/lookup/quickstart/authenticated-lookup">
    Get the current user's profile
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/users/lookup/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-user-by-id">
    Full endpoint documentation
  </Card>
</CardGroup>


# User lookup endpoints migration overview
Source: https://docs.x.com/x-api/users/lookup/migrate/overview

Map Standard v1.1 users/show, users/lookup, and account/verify_credentials to X API v2 user lookup endpoints for a smooth migration.

## 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`<br /><br />`/2/users/:id`<br /><br />`/2/users/by`<br /><br />`/2/users/by/:username`                                                                                                                                                                                                                                                      |
| [Authentication](/resources/fundamentals/authentication)                                                                                                           | OAuth 1.0a User Context                                                                                                                    | OAuth 1.0a User Context<br /><br />App only<br /><br />OAuth 2.0 Authorization Code with PKCE                                                                                                                                                                                                                                                         |
| Default request [rate limits](/resources/fundamentals/rate-limits)                                                                                                 | 900 requests per 15 min (per user)<br /><br />/show - 900 requests per 15 min (per app)  <br />/lookup - 300 requests per 15 min (per app) | 900 requests per 15 min (per user)<br /><br />300 requests per 15 min (per app)                                                                                                                                                                                                                                                                       |
| Maximum Users per response                                                                                                                                         | /show -  1<br /><br />/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)<br /><br />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")


# v1 to v2
Source: https://docs.x.com/x-api/users/lookup/migrate/standard-to-twitter-api-v2

If you have been working with the standard v1.1 GET users/show and GET users/lookup, the goal of. Reference for the X API v2 standard tier covering migrate.

### 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 support 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**


# Authenticated User Quickstart
Source: https://docs.x.com/x-api/users/lookup/quickstart/authenticated-lookup

This guide walks you through retrieving the currently authenticated user's profile using the. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through retrieving the currently authenticated user's profile using the `/me` endpoint.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Get the authenticated user

Make a request to the `/me` endpoint with a User Access Token:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/me?\
  user.fields=created_at,description,verified,public_metrics,profile_image_url" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get the authenticated user
  response = client.users.get_me(
      user_fields=["created_at", "description", "verified", "public_metrics", "profile_image_url"]
  )

  print(f"Username: {response.data.username}")
  print(f"ID: {response.data.id}")
  print(f"Followers: {response.data.public_metrics.followers_count}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get the authenticated user
  const response = await client.users.getMe({
    userFields: ["created_at", "description", "verified", "public_metrics", "profile_image_url"],
  });

  console.log(`Username: ${response.data?.username}`);
  console.log(`ID: ${response.data?.id}`);
  console.log(`Followers: ${response.data?.public_metrics?.followers_count}`);
  ```
</CodeGroup>

***

## Response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "description": "The voice of the X developer community",
    "verified": true,
    "profile_image_url": "https://pbs.twimg.com/profile_images/...",
    "public_metrics": {
      "followers_count": 583423,
      "following_count": 2048,
      "tweet_count": 14052,
      "listed_count": 1672
    }
  }
}
```

***

## Use case

The `/me` endpoint is essential when:

* **Verifying authentication** — Confirm the user is properly authenticated
* **Getting the user ID** — Retrieve the authenticated user's ID for other API calls
* **Personalizing experiences** — Display the user's profile in your app
* **On behalf of requests** — Know who you're making requests for

***

## Include pinned Post

Request the user's pinned Post:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/me?\
  user.fields=pinned_tweet_id&\
  expansions=pinned_tweet_id&\
  tweet.fields=created_at,text" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get authenticated user with pinned Post
  response = client.users.get_me(
      user_fields=["pinned_tweet_id"],
      expansions=["pinned_tweet_id"],
      tweet_fields=["created_at", "text"]
  )

  print(f"Username: {response.data.username}")
  # Pinned Post is in response.includes.tweets
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get authenticated user with pinned Post
  const response = await client.users.getMe({
    userFields: ["pinned_tweet_id"],
    expansions: ["pinned_tweet_id"],
    tweetFields: ["created_at", "text"],
  });

  console.log(`Username: ${response.data?.username}`);
  // Pinned Post is in response.includes?.tweets
  ```
</CodeGroup>

### Response with expansion

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers",
    "pinned_tweet_id": "1234567890"
  },
  "includes": {
    "tweets": [
      {
        "id": "1234567890",
        "text": "Welcome to my profile!",
        "created_at": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}
```

***

## Available fields

| Field               | Description               |
| :------------------ | :------------------------ |
| `created_at`        | Account creation date     |
| `description`       | User bio                  |
| `profile_image_url` | Avatar URL                |
| `verified`          | Verification status       |
| `public_metrics`    | Follower/following counts |
| `location`          | User-defined location     |
| `url`               | User's website            |
| `protected`         | Protected account status  |
| `pinned_tweet_id`   | Pinned Post ID            |

***

## Authentication requirement

<Warning>
  The `/me` endpoint requires User Context authentication. App-Only (Bearer Token) authentication is not supported.
</Warning>

Use either:

* [OAuth 1.0a User Context](/resources/fundamentals/authentication)
* [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2)

***

## Next steps

<CardGroup>
  <Card title="User lookup" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-people.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=9d5f3f82edcd2a4070364193436e7980" href="/x-api/users/lookup/quickstart/user-lookup">
    Look up other users
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/users/lookup/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-my-user">
    Full endpoint documentation
  </Card>
</CardGroup>


# User Lookup Quickstart
Source: https://docs.x.com/x-api/users/lookup/quickstart/user-lookup

This guide walks you through looking up users by their ID or username. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through looking up users by their ID or username.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token
</Note>

***

## Look up by ID

### Single user

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/2244994945?\
  user.fields=created_at,description,verified,public_metrics" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get user by ID
  response = client.users.get(
      "2244994945",
      user_fields=["created_at", "description", "verified", "public_metrics"]
  )

  print(f"Name: {response.data.name}")
  print(f"Username: {response.data.username}")
  print(f"Followers: {response.data.public_metrics.followers_count}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get user by ID
  const response = await client.users.get("2244994945", {
    userFields: ["created_at", "description", "verified", "public_metrics"],
  });

  console.log(`Name: ${response.data?.name}`);
  console.log(`Username: ${response.data?.username}`);
  console.log(`Followers: ${response.data?.public_metrics?.followers_count}`);
  ```
</CodeGroup>

### Response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "description": "The voice of the X developer community",
    "verified": true,
    "public_metrics": {
      "followers_count": 583423,
      "following_count": 2048,
      "tweet_count": 14052,
      "listed_count": 1672
    }
  }
}
```

### Multiple users

Look up to 100 users at once:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users?\
  ids=2244994945,783214,6253282&\
  user.fields=username,verified" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get multiple users by ID
  response = client.users.get_users(
      ids=["2244994945", "783214", "6253282"],
      user_fields=["username", "verified"]
  )

  for user in response.data:
      print(f"{user.username} - Verified: {user.verified}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get multiple users by ID
  const response = await client.users.getUsers({
    ids: ["2244994945", "783214", "6253282"],
    userFields: ["username", "verified"],
  });

  response.data?.forEach((user) => {
    console.log(`${user.username} - Verified: ${user.verified}`);
  });
  ```
</CodeGroup>

***

## Look up by username

### Single user

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/by/username/XDevelopers?\
  user.fields=created_at,description,verified" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get user by username
  response = client.users.get_by_username(
      "XDevelopers",
      user_fields=["created_at", "description", "verified"]
  )

  print(f"ID: {response.data.id}")
  print(f"Name: {response.data.name}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get user by username
  const response = await client.users.getByUsername("XDevelopers", {
    userFields: ["created_at", "description", "verified"],
  });

  console.log(`ID: ${response.data?.id}`);
  console.log(`Name: ${response.data?.name}`);
  ```
</CodeGroup>

### Multiple users

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/by?\
  usernames=XDevelopers,X,elonmusk&\
  user.fields=created_at,verified" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get multiple users by username
  response = client.users.get_users_by_usernames(
      usernames=["XDevelopers", "X", "elonmusk"],
      user_fields=["created_at", "verified"]
  )

  for user in response.data:
      print(f"{user.username} - {user.created_at}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get multiple users by username
  const response = await client.users.getUsersByUsernames({
    usernames: ["XDevelopers", "X", "elonmusk"],
    userFields: ["created_at", "verified"],
  });

  response.data?.forEach((user) => {
    console.log(`${user.username} - ${user.created_at}`);
  });
  ```
</CodeGroup>

***

## Available fields

| Field               | Description               |
| :------------------ | :------------------------ |
| `created_at`        | Account creation date     |
| `description`       | User bio                  |
| `profile_image_url` | Avatar URL                |
| `verified`          | Verification status       |
| `public_metrics`    | Follower/following counts |
| `location`          | User-defined location     |
| `url`               | User's website            |
| `protected`         | Protected account status  |
| `pinned_tweet_id`   | Pinned Post ID            |

***

## Handle errors

### User not found

```json theme={null}
{
  "errors": [
    {
      "resource_type": "user",
      "title": "Not Found Error",
      "detail": "Could not find user with username: [nonexistent_user]."
    }
  ]
}
```

### Protected user

Protected users' data is still returned, but you won't be able to access their Posts unless you follow them.

***

## Next steps

<CardGroup>
  <Card title="Authenticated user" icon="user-check" href="/x-api/users/lookup/quickstart/authenticated-lookup">
    Get the current user
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/users/lookup/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-user-by-id">
    Full endpoint documentation
  </Card>
</CardGroup>


# Mute User
Source: https://docs.x.com/x-api/users/mute-user

post /2/users/{id}/muting



# Integration Guide
Source: https://docs.x.com/x-api/users/mutes/integrate

This guide covers the key concepts you need to integrate the mutes endpoints into your application. Reference for the X API v2 standard tier covering mutes.

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                   |

<Warning>
  App-Only authentication is not supported. You must authenticate on behalf of a user.
</Warning>

### 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 theme={null}
{
  "data": [
    {
      "id": "1234567890",
      "name": "Example User",
      "username": "example"
    }
  ]
}
```

### Available fields

<Accordion title="user.fields">
  | Field               | Description               |
  | :------------------ | :------------------------ |
  | `created_at`        | Account creation date     |
  | `description`       | User bio                  |
  | `profile_image_url` | Avatar URL                |
  | `public_metrics`    | Follower/following counts |
  | `verified`          | Verification status       |
</Accordion>

<Accordion title="expansions">
  | Expansion         | Description        |
  | :---------------- | :----------------- |
  | `pinned_tweet_id` | User's pinned Post |
</Accordion>

### Example with fields

<CodeGroup>
  ```bash cURL theme={null}
  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 title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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}`);
    });
  }
  ```
</CodeGroup>

***

## Pagination

For users with large mute lists, results are paginated:

<CodeGroup>
  ```bash cURL theme={null}
  # 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 title="Python SDK" lines wrap icon="python" theme={null}
  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 title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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`);
  ```
</CodeGroup>

<Card title="Pagination guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/fundamentals/pagination">
  Learn more about pagination
</Card>

***

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

<Tip>
  Muting is private — the muted user is not notified and cannot tell they've been muted.
</Tip>

***

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

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/users/mutes/quickstart/manage-mutes-quickstart">
    Make your first mutes request
  </Card>

  <Card title="Blocks" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-block.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=702a65b4001948aebcc42635b8e2eac7" href="/x-api/users/blocks/introduction">
    Block users instead of muting
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-muting">
    Full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>


# Mutes
Source: https://docs.x.com/x-api/users/mutes/introduction

Use the X API v2 Mutes endpoints to mute and unmute accounts on behalf of the authenticated user and retrieve the full list of users they have muted on X.

The Mutes endpoints let you mute and unmute users, and retrieve the list of users muted by the authenticated user.

## Overview

<CardGroup>
  <Card title="Mute" icon="volume-xmark">
    Mute a user
  </Card>

  <Card title="Unmute" icon="volume-high">
    Unmute a user
  </Card>

  <Card title="Muted users" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5">
    Get your muted user list
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                                                      | Description     |
| :----- | :---------------------------------------------------------------------------- | :-------------- |
| GET    | [`/2/users/:id/muting`](/x-api/users/get-muting)                              | Get muted users |
| POST   | [`/2/users/:id/muting`](/x-api/users/mute-user)                               | Mute a user     |
| DELETE | [`/2/users/:source_user_id/muting/:target_user_id`](/x-api/users/unmute-user) | Unmute a user   |

***

## Example: Get muted users

```bash theme={null}
curl "https://api.x.com/2/users/123456789/muting?\
user.fields=username,description" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
```

## Example: Mute a user

```bash theme={null}
curl -X POST "https://api.x.com/2/users/123456789/muting" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_user_id": "9876543210"}'
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * User Access Tokens via [OAuth 2.0 PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2)
</Note>

<CardGroup>
  <Card title="Mutes lookup quickstart" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/users/mutes/quickstart/mutes-lookup">
    Get your muted users
  </Card>

  <Card title="Manage mutes quickstart" icon="volume-xmark" href="/x-api/users/mutes/quickstart/manage-mutes-quickstart">
    Mute and unmute users
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/users/mutes/integrate">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-muting">
    Full endpoint documentation
  </Card>
</CardGroup>


# Manage mutes
Source: https://docs.x.com/x-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2

If you have been working with the standard v1.1 POST mutes/users/create and POST. Reference for the X API v2 standard tier covering migrate.

### 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](https://api.x.com/1.1/mutes/users/create.json)
    (mute a user)
  * POST [https://api.x.com/1.1/mutes/users/destroy.json](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](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](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


# Mutes lookup
Source: https://docs.x.com/x-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2

If you have been working with the standard v1.1 GET mutes/users/ids and GET mutes/users/list. Reference for the X API v2 standard tier covering migrate.

### 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](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](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](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


# Mutes endpoints migration overview
Source: https://docs.x.com/x-api/users/mutes/migrate/overview

Migrate mutes lookup and manage mutes integrations from Standard v1.1 to X API v2 with mapped endpoints, parameters, and rate limits.

## 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)**                          | **[https://api.x.com](https://api.x.com)**                                                                                                                                                                                                                                                                                                            |
| Endpoint path                                                                                                                                                          | **/1.1/mutes/users/ids.json**<br /><br />/1.1/mutes/users/list.json | **/2/users/:id/muting**                                                                                                                                                                                                                                                                                                                               |
| [Authentication](/resources/fundamentals/authentication)                                                                                                               | OAuth 1.0a User Context                                             | OAuth 1.0a User Context<br /><br />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)<br /><br />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) | [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<br /><br />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) | [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<br /><br />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)


# Manage Mutes
Source: https://docs.x.com/x-api/users/mutes/quickstart/manage-mutes-quickstart

This guide walks you through muting and unmuting users using the X API. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through muting and unmuting users using the X API.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Mute a user

<Steps>
  <Step title="Get your user ID">
    You need your authenticated user's ID. You can find it using the [user lookup endpoint](/x-api/users/lookup/introduction) or from your Access Token (the numeric part is your user ID).
  </Step>

  <Step title="Get the target user ID">
    Find the user ID of the account you want to mute using the [user lookup endpoint](/x-api/users/lookup/introduction).
  </Step>

  <Step title="Send the mute request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.x.com/2/users/123456789/muting" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"target_user_id": "9876543210"}'
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      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="9876543210"
      )

      print(f"Muting: {response.data.muting}")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      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: "9876543210",
      });

      console.log(`Muting: ${response.data?.muting}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": {
        "muting": true
      }
    }
    ```
  </Step>
</Steps>

***

## Unmute a user

Remove a mute from a user:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.x.com/2/users/123456789/muting/9876543210" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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="9876543210"
  )

  print(f"Muting: {response.data.muting}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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", "9876543210");

  console.log(`Muting: ${response.data?.muting}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "muting": false
  }
}
```

***

## Mute vs Block

| Feature             | Mute | Block |
| :------------------ | :--- | :---- |
| See their Posts     | No   | No    |
| They see your Posts | Yes  | No    |
| They can follow you | Yes  | No    |
| They can DM you     | Yes  | No    |
| They know           | No   | Yes   |

***

## Next steps

<CardGroup>
  <Card title="Mutes lookup" icon="volume-xmark" href="/x-api/users/mutes/quickstart/mutes-lookup">
    Get your muted users
  </Card>

  <Card title="Blocks" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-block.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=702a65b4001948aebcc42635b8e2eac7" href="/x-api/users/blocks/quickstart">
    Block users instead
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/mute-user-by-user-id">
    Full endpoint documentation
  </Card>
</CardGroup>


# Mutes Lookup
Source: https://docs.x.com/x-api/users/mutes/quickstart/mutes-lookup

This guide walks you through retrieving your muted users list using the X API. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through retrieving your muted users list using the X API.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)
</Note>

***

## Get your muted users

<Steps>
  <Step title="Get your user ID">
    You need your authenticated user's ID. You can find it using the [user lookup endpoint](/x-api/users/lookup/introduction) or from your Access Token (the numeric part is your user ID).
  </Step>

  <Step title="Request your muted users">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.x.com/2/users/123456789/muting?\
      user.fields=created_at,username,verified&\
      max_results=100" \
        -H "Authorization: Bearer $USER_ACCESS_TOKEN"
      ```

      ```python title="Python SDK" lines wrap icon="python" theme={null}
      from xdk import Client

      client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

      # Get muted users with pagination
      for page in client.users.get_muting(
          "123456789",
          user_fields=["created_at", "username", "verified"],
          max_results=100
      ):
          for user in page.data:
              print(f"{user.username} - Muted")
      ```

      ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
      import { Client } from "@xdevplatform/xdk";

      const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

      // Get muted users with pagination
      const paginator = client.users.getMuting("123456789", {
        userFields: ["created_at", "username", "verified"],
        maxResults: 100,
      });

      for await (const page of paginator) {
        page.data?.forEach((user) => {
          console.log(`${user.username} - Muted`);
        });
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the response">
    ```json theme={null}
    {
      "data": [
        {
          "id": "2244994945",
          "name": "X Developers",
          "username": "XDevelopers",
          "created_at": "2013-12-14T04:35:55.000Z",
          "verified": true
        }
      ],
      "meta": {
        "result_count": 1,
        "next_token": "1710819323648428707"
      }
    }
    ```
  </Step>
</Steps>

***

## Include additional data

Use expansions to get related data like pinned Posts:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/123456789/muting?\
  user.fields=created_at&\
  expansions=pinned_tweet_id&\
  tweet.fields=created_at" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Get muted users with expansions
  for page in client.users.get_muting(
      "123456789",
      user_fields=["created_at"],
      expansions=["pinned_tweet_id"],
      tweet_fields=["created_at"]
  ):
      for user in page.data:
          print(f"{user.username}")
      # Pinned Posts are in page.includes.tweets
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Get muted users with expansions
  const paginator = client.users.getMuting("123456789", {
    userFields: ["created_at"],
    expansions: ["pinned_tweet_id"],
    tweetFields: ["created_at"],
  });

  for await (const page of paginator) {
    page.data?.forEach((user) => {
      console.log(user.username);
    });
    // Pinned Posts are in page.includes?.tweets
  }
  ```
</CodeGroup>

### Response with expansion

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "username": "XDevelopers",
      "created_at": "2013-12-14T04:35:55.000Z",
      "id": "2244994945",
      "name": "X Developers",
      "pinned_tweet_id": "1430984356139470849"
    }
  ],
  "includes": {
    "tweets": [
      {
        "created_at": "2021-08-26T20:03:51.000Z",
        "id": "1430984356139470849",
        "text": "Help us build a better X Developer Platform!..."
      }
    ]
  },
  "meta": {
    "result_count": 1
  }
}
```

***

## Paginate through results

The SDKs handle pagination automatically. For cURL, use the `next_token` from the response:

```bash theme={null}
curl "https://api.x.com/2/users/123456789/muting?\
max_results=100&\
pagination_token=1710819323648428707" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
```

***

## Next steps

<CardGroup>
  <Card title="Manage mutes" icon="volume-xmark" href="/x-api/users/mutes/quickstart/manage-mutes-quickstart">
    Mute and unmute users
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-muting">
    Full endpoint documentation
  </Card>
</CardGroup>


# Pin List
Source: https://docs.x.com/x-api/users/pin-list

post /2/users/{id}/pinned_lists
Causes the authenticated user to pin a specific List by its ID.



# Repost Post
Source: https://docs.x.com/x-api/users/repost-post

post /2/users/{id}/retweets
Causes the authenticated user to repost a specific Post by its ID.



# Search Users
Source: https://docs.x.com/x-api/users/search-users

get /2/users/search



# User Search
Source: https://docs.x.com/x-api/users/search/introduction

Search X users by keyword with the X API v2 User search endpoint to find accounts by name, handle, bio terms, and other public profile fields and metadata.

The User Search endpoint lets you search for users by keyword. Find users by name, username, or content in their bio.

## Overview

<CardGroup>
  <Card title="Keyword search" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-search.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=8c11ad89387b7c09ced1553d5c232834">
    Search by name, username, or bio
  </Card>

  <Card title="Discover users" icon="user-plus">
    Find relevant accounts
  </Card>
</CardGroup>

***

## Endpoint

| Method | Endpoint                                       | Description      |
| :----- | :--------------------------------------------- | :--------------- |
| GET    | [`/2/users/search`](/x-api/users/search-users) | Search for users |

***

## Example request

```bash theme={null}
curl "https://api.x.com/2/users/search?\
query=python%20developer&\
user.fields=description,verified,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

## Example response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "id": "1234567890",
      "name": "Python Developer",
      "username": "pythondev",
      "description": "Building cool things with Python",
      "verified": false,
      "public_metrics": {
        "followers_count": 5000,
        "following_count": 200,
        "tweet_count": 1500
      }
    }
  ],
  "meta": {
    "result_count": 1
  }
}
```

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * Your App's [keys and tokens](/resources/fundamentals/authentication)
</Note>

<CardGroup>
  <Card title="User lookup" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-person.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=507a4bbcdcf5744bd18781508002e305" href="/x-api/users/lookup/introduction">
    Look up users by ID or username
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/user-search">
    Full endpoint documentation
  </Card>
</CardGroup>


# Unblock Users Dms
Source: https://docs.x.com/x-api/users/unblock-dms

post /2/users/{id}/dm/unblock



# Unblock Users Dms
Source: https://docs.x.com/x-api/users/unblock-users-dms

post /2/users/{id}/dm/unblock



# Unfollow a List
Source: https://docs.x.com/x-api/users/unfollow-a-list

delete /2/users/{id}/followed_lists/{list_id}
Causes the authenticated user to unfollow a List by its ID.



# Unfollow a List
Source: https://docs.x.com/x-api/users/unfollow-list

delete /2/users/{id}/followed_lists/{list_id}
Causes the authenticated user to unfollow a List by its ID.



# Unfollow User
Source: https://docs.x.com/x-api/users/unfollow-user

delete /2/users/{source_user_id}/following/{target_user_id}
Causes the authenticated user to unfollow a specific user by their ID.



# Unlike Post
Source: https://docs.x.com/x-api/users/unlike-post

delete /2/users/{id}/likes/{tweet_id}



# Unmute User
Source: https://docs.x.com/x-api/users/unmute-user

delete /2/users/{source_user_id}/muting/{target_user_id}
Causes the authenticated user to unmute the target user.



# Unpin a List
Source: https://docs.x.com/x-api/users/unpin-a-list

delete /2/users/{id}/pinned_lists/{list_id}
Causes the authenticated user to unpin a List by its ID.



# Unpin a List
Source: https://docs.x.com/x-api/users/unpin-list

delete /2/users/{id}/pinned_lists/{list_id}
Causes the authenticated user to unpin a List by its ID.



# Unrepost Post
Source: https://docs.x.com/x-api/users/unrepost-post

delete /2/users/{id}/retweets/{source_tweet_id}
Causes the authenticated user to unrepost a specific Post by its ID.



# Create replay job for webhook
Source: https://docs.x.com/x-api/webhooks/create-replay-job-for-webhook

post /2/webhooks/replay
Creates a replay job to retrieve events from up to the past 24 hours for all events delivered or attempted to be delivered to the webhook.



# Create stream link
Source: https://docs.x.com/x-api/webhooks/create-stream-link

post /2/tweets/search/webhooks/{webhook_id}
Creates a link to deliver FilteredStream events to the given webhook.



# Create webhook
Source: https://docs.x.com/x-api/webhooks/create-webhook

post /2/webhooks
Creates a new webhook configuration.



# Delete stream link
Source: https://docs.x.com/x-api/webhooks/delete-stream-link

delete /2/tweets/search/webhooks/{webhook_id}
Deletes the link delivering FilteredStream events to the given webhook.



# Delete webhook
Source: https://docs.x.com/x-api/webhooks/delete-webhook

delete /2/webhooks/{webhook_id}
Deletes an existing webhook configuration.



# Get stream links
Source: https://docs.x.com/x-api/webhooks/get-stream-links

get /2/tweets/search/webhooks
Get a list of webhook links associated with a filtered stream ruleset.



# Get webhook
Source: https://docs.x.com/x-api/webhooks/get-webhook

get /2/webhooks
Get a list of webhook configs associated with a client app.



# V2 Webhooks API
Source: https://docs.x.com/x-api/webhooks/introduction

The V2 Webhooks API enables developers to receive real-time event notifications from X accounts. Reference for the X API v2 standard tier covering webhooks.

The V2 Webhooks API enables developers to receive real-time event notifications from X accounts via webhook-based JSON messages. These APIs allow you to register and manage webhooks, develop consumer applications to process events, and ensure secure communication through challenge-response checks (CRC) and signature headers.

## Overview

<CardGroup>
  <Card title="Real-time delivery" icon="bolt">
    Receive events instantly as they occur
  </Card>

  <Card title="Push-based" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e">
    Data sent directly to your server — no polling
  </Card>

  <Card title="Secure" icon="https://mintcdn.com/x-preview/cfyQtgCdwk8p69aa/icons/xds/icon-shield-keyhole.svg?fit=max&auto=format&n=cfyQtgCdwk8p69aa&q=85&s=a0e05514090c8a6af232297bfb9c4055">
    CRC validation and signature verification
  </Card>

  <Card title="Reliable" icon="gauge">
    Retry and recovery support
  </Card>
</CardGroup>

***

## Products that support webhooks

These are the products that currently support delivering events via webhook:

| Product                                                            | Description                                             |
| :----------------------------------------------------------------- | :------------------------------------------------------ |
| [X Activity API (XAA)](/x-api/activity/introduction)               | Receive real-time events for activity happening on X    |
| [Account Activity API (AAA)](/x-api/account-activity/introduction) | Receive real-time events tied to specific user accounts |
| [Filtered Stream Webhooks](/x-api/webhooks/stream/introduction)    | Receive filtered stream Posts via webhook delivery      |

***

## How webhooks work

```mermaid actions={false} theme={null}
flowchart LR
    A["X Event<br/>Occurs"] --> B["X Server"] --> C["Your<br/>Webhook URL"]
```

1. **Event occurs** — A user posts, sends a DM, gets followed, etc.
2. **X sends a POST request** — JSON event payload sent to your registered webhook URL
3. **You process the event** — Your server handles the event data
4. **Respond with 200 OK** — Return a 200 status to acknowledge receipt

***

## Webhook requirements

| Requirement               | Description                                                                                                      |
| :------------------------ | :--------------------------------------------------------------------------------------------------------------- |
| **HTTPS**                 | Webhook URL must use HTTPS                                                                                       |
| **Publicly accessible**   | URL must be reachable from the internet                                                                          |
| **No port specification** | The URL cannot include a port (e.g., `https://mydomain.com:5000/webhook` will not work)                          |
| **Fast response**         | Respond within 10 seconds                                                                                        |
| **200 OK**                | Return 200 status to acknowledge receipt                                                                         |
| **CRC support**           | Must respond to Challenge-Response Check GET requests ([learn more](/x-api/webhooks/quickstart#2-the-crc-check)) |

***

## Endpoints

| Method | Endpoint                                                              | Description                               |
| :----- | :-------------------------------------------------------------------- | :---------------------------------------- |
| POST   | [`/2/webhooks`](/x-api/webhooks/create-webhook)                       | Register a new webhook                    |
| GET    | [`/2/webhooks`](/x-api/webhooks/get-webhook)                          | List registered webhooks                  |
| DELETE | [`/2/webhooks/:webhook_id`](/x-api/webhooks/delete-webhook)           | Delete a webhook                          |
| POST   | [`/2/webhooks/replay`](/x-api/webhooks/create-replay-job-for-webhook) | Create a replay job for webhook           |
| PUT    | [`/2/webhooks/:webhook_id`](/x-api/webhooks/validate-webhook)         | Trigger CRC check and re-enable a webhook |

All endpoints require **OAuth2 App Only Bearer Token** authentication.

***

## Security

X's webhook-based APIs provide two methods for confirming the security of your webhook server:

1. **Challenge-Response Check (CRC)** — X sends periodic GET requests to your webhook URL. You respond with an HMAC-SHA256 hash to prove you control the endpoint. CRC checks happen on initial registration, hourly, and on manual re-validation.

2. **Signature verification** — Each POST request from X includes an `x-twitter-webhooks-signature` header. You can verify this signature to confirm X is the source of incoming events.

<Card title="See full implementation details" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/webhooks/quickstart">
  Step-by-step CRC setup, code examples, and signature verification
</Card>

***

## Webhook validation

A CRC check is sent to your webhook in the following cases:

* Immediately upon creation
* On an explicit PUT request (`PUT /2/webhooks/{id}`)
* Periodically every 30 minutes, but only if the webhook has not been successfully validated in the past 24 hours

A webhook is marked as **invalid** when:

* It returns an invalid response to a CRC check
  * Returns a 2XX status code but the `response_token` is incorrect
  * Returns a 3XX status code
  * Results in an SSL exception
* It experiences persistent transient errors such that it has not successfully validated for more than 28 hours (includes a 4-hour grace period for transient issues)
  * The following responses are treated as transient errors:
    * 4XX status code
    * 5XX status code
    * Request timeout
    * Channel closed

You can check the valid/invalid status of a webhook using the `GET /2/webhooks` endpoint or via the toolbox in the Developer Console.

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * A publicly accessible HTTPS endpoint
  * Your app's **consumer secret** (API secret key) for CRC validation
</Note>

<CardGroup>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/webhooks/quickstart">
    Set up your webhook end-to-end
  </Card>

  <Card title="Filtered Stream Webhooks" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e" href="/x-api/webhooks/stream/introduction">
    Receive filtered Posts via webhook
  </Card>

  <Card title="Account Activity API" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bell.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=5e0b3dcfbb39ba3d4619931d7cd927d1" href="/x-api/account-activity/introduction">
    Receive account events via webhook
  </Card>

  <Card title="Sample apps" icon="github" href="/x-api/webhooks/quickstart#sample-apps">
    Working code examples
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.x.com/x-api/webhooks/quickstart

This guide walks you through setting up a webhook consumer app, implementing the. Reference for the X API v2 standard tier covering webhooks.

This guide walks you through setting up a webhook consumer app, implementing the Challenge-Response Check (CRC), securing incoming events, and registering your webhook with X.

## 1. Develop a webhook consumer app

To register a webhook with your X app, you need to develop, deploy, and host a web app that receives X webhook events and responds to CRC security requests.

### URL requirements

Create a web app with a publicly accessible HTTPS URL that will act as the webhook endpoint to receive events:

* The URI **path** is up to you. These examples are all valid:
  * `https://mydomain.com/service/listen`
  * `https://mydomain.com/webhook/twitter`
* The URL **cannot** include a port specification (e.g., `https://mydomain.com:5000/webhook` will **not** work)

### What your app needs to handle

Your webhook endpoint must handle two types of HTTP requests:

| Request type | Purpose                                                                  |
| :----------- | :----------------------------------------------------------------------- |
| **GET**      | [CRC validation](#2-the-crc-check) — X verifies you control the endpoint |
| **POST**     | Event delivery — X sends JSON event payloads                             |

***

## 2. The CRC check

The Challenge-Response Check (CRC) is how X validates that the callback URL you provided is valid and that **you control it**. Your web app must correctly respond to CRC requests to register and maintain your webhook.

### When CRC is triggered

| Trigger                  | Description                                       |
| :----------------------- | :------------------------------------------------ |
| **Initial registration** | When you call `POST /2/webhooks`                  |
| **Hourly validation**    | X automatically validates your webhook every hour |
| **Manual re-validation** | When you call `PUT /2/webhooks/:webhook_id`       |

If your webhook fails a CRC check, it will be marked as `invalid` and will **stop receiving events** until it passes again.

### How the CRC works

When X sends a CRC, it makes a **GET request** to your webhook URL with a `crc_token` query parameter:

```
GET https://your-webhook-url.com/webhook?crc_token=challenge_string
```

Your application must respond with a JSON body containing a `response_token`:

```json theme={null}
{
  "response_token": "sha256=<base64_encoded_hmac_hash>"
}
```

### How to build the CRC response

1. Use the `crc_token` value from the query parameter as the **message**
2. Use your app's **consumer secret** (API secret key) as the **key**
3. Create an **HMAC SHA-256** hash
4. **Base64 encode** the result
5. Prepend `sha256=` to the encoded string

<Warning>
  **Important:** Your web app must use your app's **consumer secret** (API secret key) for the CRC encryption — not your bearer token or access token.
</Warning>

### Example: Python

```python title="Example" lines wrap icon="python" theme={null}
import hmac
import hashlib
import base64

def handle_crc(crc_token, consumer_secret):
    """
    Respond to a Twitter CRC check.
    
    Args:
        crc_token: The crc_token query parameter from the GET request
        consumer_secret: Your app's consumer secret (API secret key)
    
    Returns:
        dict with the response_token
    """
    sha256_hash = hmac.new(
        consumer_secret.encode('utf-8'),
        crc_token.encode('utf-8'),
        hashlib.sha256
    ).digest()

    return {
        "response_token": "sha256=" + base64.b64encode(sha256_hash).decode('utf-8')
    }
```

### Example: Node.js

```javascript title="Example" lines wrap icon="square-js" theme={null}
const crypto = require('crypto');

function handleCrc(crcToken, consumerSecret) {
  const hmac = crypto
    .createHmac('sha256', consumerSecret)
    .update(crcToken)
    .digest('base64');

  return {
    response_token: `sha256=${hmac}`
  };
}
```

### Example: Flask (full endpoint)

This example shows a complete webhook endpoint that handles both CRC validation (GET) and event delivery (POST):

```python title="Example" expandable lines wrap icon="python" theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import base64

app = Flask(__name__)

CONSUMER_SECRET = "your_consumer_secret_here"

@app.route("/webhook", methods=["GET", "POST"])
def webhook():
    if request.method == "GET":
        # Handle CRC check
        crc_token = request.args.get("crc_token")
        if crc_token:
            sha256_hash = hmac.new(
                CONSUMER_SECRET.encode("utf-8"),
                crc_token.encode("utf-8"),
                hashlib.sha256,
            ).digest()
            response_token = "sha256=" + base64.b64encode(sha256_hash).decode("utf-8")
            return jsonify({"response_token": response_token}), 200
        return "Missing crc_token", 400

    elif request.method == "POST":
        # Handle incoming webhook events
        event = request.get_json()
        print("Received event:", event)
        return "", 200
```

***

## 3. Securing webhooks

X's webhook-based APIs provide two methods for confirming the security of your webhook server:

### Challenge-Response Check (CRC)

The CRC enables X to confirm ownership of the web app receiving webhook events. See [Step 2](#2-the-crc-check) above for full implementation details.

### Signature verification

Each POST request from X includes an `x-twitter-webhooks-signature` header that enables you to confirm that X is the source of the incoming webhook.

To verify the signature:

1. Get the `x-twitter-webhooks-signature` header value from the incoming request
2. Create an HMAC SHA-256 hash using your **consumer secret** as the key and the **raw request body** as the message
3. Base64 encode the hash and prepend `sha256=`
4. Compare your computed value to the header value — they should match

```python title="Example" expandable lines wrap icon="python" theme={null}
import hmac
import hashlib
import base64

def verify_signature(payload, signature_header, consumer_secret):
    """
    Verify that a webhook POST request actually came from X.
    
    Args:
        payload: The raw request body (bytes)
        signature_header: The x-twitter-webhooks-signature header value
        consumer_secret: Your app's consumer secret
    
    Returns:
        True if the signature is valid
    """
    expected = "sha256=" + base64.b64encode(
        hmac.new(
            consumer_secret.encode("utf-8"),
            payload,
            hashlib.sha256
        ).digest()
    ).decode("utf-8")
    
    return hmac.compare_digest(expected, signature_header)
```

***

## 4. Register your webhook

Once your app can handle CRC checks, register your webhook URL by making a `POST /2/webhooks` request. When you make this request, X will immediately send a CRC request to your web app to verify ownership.

All webhook management endpoints require **OAuth2 App Only Bearer Token** authentication.

### Create a webhook

**`POST /2/webhooks`** — [API Reference](/x-api/webhooks/create-webhook)

```bash theme={null}
curl --request POST \
  --url 'https://api.x.com/2/webhooks' \
  --header 'Authorization: Bearer $BEARER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://yourdomain.com/webhooks/twitter"
  }'
```

**Success response (200 OK):**

A successful response indicates the webhook was created and the initial CRC check passed.

```json theme={null}
{
  "data": {
    "id": "1234567890",
    "url": "https://yourdomain.com/webhooks/twitter",
    "valid": true,
    "created_at": "2025-01-15T12:00:00.000Z"
  }
}
```

When a webhook is successfully registered, the response includes a **webhook ID**. This ID is needed when making requests to products that support webhooks (e.g., linking to Filtered Stream, or creating subscriptions for Account Activity).

**Common failure reasons:**

| Reason                 | Description                                                                                    |
| :--------------------- | :--------------------------------------------------------------------------------------------- |
| `CrcValidationFailed`  | Your callback URL did not respond correctly to the CRC check (e.g., timed out, wrong response) |
| `UrlValidationFailed`  | The callback URL does not meet requirements (e.g., not `https`, invalid format)                |
| `DuplicateUrlFailed`   | A webhook is already registered by your application for this URL                               |
| `WebhookLimitExceeded` | Your application has reached the maximum number of allowed webhooks                            |

### View webhooks

**`GET /2/webhooks`** — [API Reference](/x-api/webhooks/get-webhook)

Retrieve all webhook configurations associated with your application.

```bash theme={null}
curl --request GET \
  --url 'https://api.x.com/2/webhooks' \
  --header 'Authorization: Bearer $BEARER_TOKEN'
```

**Response (with one webhook):**

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "created_at": "2025-01-15T12:00:00.000Z",
      "id": "1234567890",
      "url": "https://yourdomain.com/webhooks/twitter",
      "valid": true
    }
  ],
  "meta": {
    "result_count": 1
  }
}
```

**Response (with no webhooks):**

```json theme={null}
{
  "data": [],
  "meta": {
    "result_count": 0
  }
}
```

### Delete a webhook

**`DELETE /2/webhooks/:webhook_id`** — [API Reference](/x-api/webhooks/delete-webhook)

Delete a webhook using its `webhook_id` (obtained from the create or list response).

```bash theme={null}
curl --request DELETE \
  --url 'https://api.x.com/2/webhooks/1234567890' \
  --header 'Authorization: Bearer $BEARER_TOKEN'
```

**Response:**

```json theme={null}
{
  "data": {
    "deleted": true
  }
}
```

| Failure reason     | Description                                                                |
| :----------------- | :------------------------------------------------------------------------- |
| `WebhookIdInvalid` | The provided `webhook_id` was not found or is not associated with your app |

### Validate and re-enable a webhook

**`PUT /2/webhooks/:webhook_id`** — [API Reference](/x-api/webhooks/validate-webhook)

Triggers a CRC check for the given webhook. If the check succeeds, the webhook is re-enabled with `valid: true`.

```bash theme={null}
curl --request PUT \
  --url 'https://api.x.com/2/webhooks/1234567890' \
  --header 'Authorization: Bearer $BEARER_TOKEN'
```

**Response:**

A 200 OK response indicates the CRC check was initiated. The `valid` field reflects the status after the check attempt. You can verify the current status using `GET /2/webhooks`.

```json theme={null}
{
  "data": {
    "valid": true
  }
}
```

| Failure reason        | Description                                                                |
| :-------------------- | :------------------------------------------------------------------------- |
| `WebhookIdInvalid`    | The provided `webhook_id` was not found or is not associated with your app |
| `CrcValidationFailed` | The callback URL did not respond correctly to the CRC check                |

***

## Testing with xurl

For testing purposes, the `xurl` tool supports temporary webhooks. Install the latest version of the [`xurl` project](https://github.com/xdevplatform/xurl) from GitHub, configure your authorization, then run:

```bash theme={null}
xurl webhook start
```

This will generate a temporary public webhook URL, automatically handle all CRC checks, and log any incoming subscription events. It's a great way to verify your setup before deploying. Example output:

```
Starting webhook server with ngrok...
Enter your ngrok authtoken (leave empty to try NGROK_AUTHTOKEN env var):

Attempting to use NGROK_AUTHTOKEN environment variable for ngrok authentication.
Configuring ngrok to forward to local port: 8080
Ngrok tunnel established!
  Forwarding URL: https://<your-ngrok-subdomain>.ngrok-free.app -> localhost:8080

Use this URL for your X API webhook registration: https://<your-ngrok-subdomain>.ngrok-free.app/webhook

Starting local HTTP server to handle requests from ngrok tunnel...
```

***

## Important notes

<Warning>
  * **All incoming Direct Messages** will be delivered via webhooks. DMs sent via [POST /2/dm\_conversations/with/:participant\_id/messages](/x-api/direct-messages/send-a-new-message-to-a-user) will also be delivered, so your app can track DMs sent from other clients.

  * 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 **deduplicate by event ID**.

  * X sends events as **POST requests** with JSON payloads. See the [Account Activity data object structure](/x-api/account-activity/introduction#account-activity-data-object-structure) for example payloads.
</Warning>

***

## Sample apps

| App                                                                                                                 | Description                                                                                                           |
| :------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------- |
| [Simple webhook server](https://github.com/m-rosinsky/XWebhookTest/blob/main/app.py)                                | A single Python script that shows how to respond to the CRC check and accept POST events                              |
| [Account Activity API dashboard](https://github.com/xdevplatform/account-activity-dashboard-enterprise/tree/master) | A web app written with [bun.sh](https://bun.sh) that lets you manage webhooks, subscriptions, and receive live events |
| [xurl testing tool](https://github.com/xdevplatform/xurl)                                                           | CLI tool for temporary webhook testing — auto-handles CRC checks and logs events                                      |

***

## Next steps

<CardGroup>
  <Card title="Filtered Stream Webhooks" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-filter.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=5d59aff402c1f2aeae0e9e44bb23400e" href="/x-api/webhooks/stream/introduction">
    Receive filtered Posts via webhook
  </Card>

  <Card title="Account Activity API" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-bell.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=5e0b3dcfbb39ba3d4619931d7cd927d1" href="/x-api/account-activity/introduction">
    Receive account events via webhook
  </Card>
</CardGroup>


# Filtered Stream Webhooks API
Source: https://docs.x.com/x-api/webhooks/stream/introduction

The filtered stream endpoint group enables developers to filter a stream of public Posts. Reference for the X API v2 standard tier covering stream.

## Overview

The filtered stream endpoint group enables developers to filter a stream of public Posts. This endpoint group’s functionality includes multiple endpoints that enable you to create and manage rules, and apply those rules to filter a stream of Posts that will return matching public Posts. This endpoint group allows users to listen for specific topics and events, monitor the conversation around competitions, understand how trends develop, and much more.

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/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. 

**Note:** This endpoint group is similar to the [v2 filtered stream endpoint](/x-api/posts/filtered-stream/introduction) for setting up your rules. The only difference is the delivery mechanisms for the Posts that match your rules.

* In case of v2 filtered stream endpoint, you have to establish a persistent connection and listen for Posts matching your rules.
* In case of this filtered stream webhook endpoint, you register your webhook, and X delivers Posts matching your rules to your webhook.

This eliminates the need for handling disconnects stemming from client drops or server-side drops from normal restarts to our service. Since we will likely be delivering hundreds of events/second, it is necessary for your
webhook server to be able to handle these simultaneous connection attempts.

This endpoint is currently available to Enterprise developers and supports the following configuration:

* 25,000+ rules per project
* Can use all operators when building your rule
* Can build rules up to 2048 characters in length
* Apply [here](/forms/enterprise-api-interest) for Enterprise access

The returned Posts from filtered stream count towards the monthly [Post cap](/x-api/fundamentals/post-cap).

<Note>
  **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).
</Note>

<div>
  <Button href="/x-api/posts/filtered-stream/quickstart">
    Quick start
  </Button>
</div>


# Quickstart
Source: https://docs.x.com/x-api/webhooks/stream/quickstart

The v2 filtered stream webhooks API is similar to the [v2 filtered stream. Reference for the X API v2 standard tier covering stream.

## Getting started with the filtered stream webhooks API

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 the rules to filter on. The difference lies in the delivery mechanism for the Posts that match your rules.

* In case of v2 filtered stream endpoint, you have to establish a persistent connection and listen for Posts matching your rules.
* In case of this filtered stream webhook endpoint, you register your webhook, and X delivers Posts matching your rules to your webhook.

This guide explains how to filter for, and receive posts using the filtered stream webhooks endpoints. There are 3 steps involved

1. Setting up your filtered stream rules
2. Creating your webhook
3. Linking your Filtered Stream instance to your webhook

Once you have linked your Filtered Stream instance to your webhook, X will send Posts that match your rules to your webhooks.

### Setting up your filtered stream rules

Filtered stream rules are made up of one or many operators that are combined using boolean logic and parentheses to help define which Posts will be delivered to your webhooks. The filtered stream webhooks API uses the same set of endpoints as the [v2 filtered stream endpoint](/x-api/posts/filtered-stream/introduction) to create and manage rules. Check out [this detailed guide](/x-api/posts/filtered-stream/integrate/build-a-rule) that demonstrates how you can build filters.

### Creating your webhook

Create a webhook to receive events by registering a publicly accessible HTTPS URL with the X API. Webhooks must handle GET requests for CRC validation and POST requests for event payloads. Follow the [Webhooks Introduction documentation](/x-api/webhooks/introduction) for detailed steps on creating and managing webhooks.

**Note:** If you already use webhooks for [Account Activity API (AAA)](/x-api/account-activity/introduction), the webhooks set up for that are exactly the same here. In fact, you can use the same webhook endpoint you use for AAA for this API, if you have the bandwidth and can separate the events.

### Linking your Filtered Stream instance to your webhook

Once your rules are set and the webhook is created, link the webhook to your Filtered Stream instance. This routes matched post events to your webhook URL.

Use the endpoint: `POST /2/tweets/search/webhooks/:webhook_id `

You can include query parameters identical to those used in the streaming endpoint `/2/tweets/search/stream` such as expansions, fields, and media options. This customizes the
data included in event payloads.

**Example:**

```bash theme={null}
curl --request POST \ 
  --url 
'https://api.x.com/2/tweets/search/webhooks/123456789012345678?ex
pansions=author_id&user.fields=username,name,id' \ 
  --header 'Authorization: Bearer $BEARER_TOKEN' 
```

Successful response example:

```json theme={null}
{ 
  "data": { 
    "provisioned": true 
  } 
}
```

**Tip:** You can link multiple webhooks to the same stream for redundancy or to receive different field sets. Each linkage can specify unique parameters.

Once you have your Filtered Stream instance to your webhook, you will start to receive Posts matching your rules like shown below:

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
    "data": {
        "id": "1346889436626259968",
        "text": "Learn how to use the user Post timeline and user mention timeline endpoints in the X API v2 to explore Post… https://t.co/56a0vZUx7i",
        "created_at": "2021-01-06T18:40:40.000Z",
        "author_id": "2244994945"
    },
    "includes": {
        "users": [
            {
                "id": "2244994945",
                "name": "Developers",
                "username": "Xdevelopers",
                "created_at": "2013-12-14T04:35:55Z",
                "protected": false
            }
        ]
    },
    "matching_rules": [
        {
            "id": "120897978112909812",
            "tag": "api-posts"
        }
    ]
}
```

### Retrieving webhooks linked to Filtered Stream

Retrieve a list of all webhooks currently linked to your Filtered Stream:

```bash theme={null}
GET /2/tweets/search/stream/webhooks 
```

Example Response:

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
    "data": {
        "links": [
            {
                "application_id": "29893711",
                "business_user_id": "1877374016438091776",
                "fields": [
                    "user.fields=username",
                    "name",
                    "id",
                    "expansions=author_id"
                ],
                "instance_id": "1877375130462289920",
                "webhook_id": "1952390923729424384"
            }
        ]
    }
}
```

### Unlinking your webhook from Filtered Stream

To stop receiving events on a specific webhook, unlink it using:

```bash theme={null}
DELETE /2/tweets/search/webhooks/:webhook_id
```

The response will be as follows:

```json theme={null}
{
    "data": {
        "deleted": true
    }
}
```


# Validate webhook
Source: https://docs.x.com/x-api/webhooks/validate-webhook

put /2/webhooks/{webhook_id}
Triggers a CRC check for a given webhook.



# Direct Message button
Source: https://docs.x.com/x-for-websites/direct-message-button

Add a Direct Message button to your website so visitors can start a conversation with your X account directly, including setup and customization options.

The Message button is a small button to help your customers easily send a Direct Message to you on X. Allow your customers to contact you to ask questions and get support from right on your website.

A Message button consists of two parts: a link to the direct message composer on X.com, and the X for Websites JavaScript to enhance the link with the recognizable Message button.

## Message creation flow

Clicking the button will link the user to the Direct Message composer, pre-populated with the values you define in the button markup.

## How to add a message button to your website

[publish.x.com](https://publish.x.com) is a simple configuration tool for to create a message button. Just enter your @screenName to get started.

### Manually

1. Create an anchor element with a `twitter-dm-button` class name. Set a `href` attribute value of `https://x.com/messages/compose` to create a link to the X direct message view. The `recipient_id` query parameter is the ID of the @username that should receive the messages.

```html theme={null}
<a href="https://x.com/messages/compose?recipient_id=3805104374"
  class="twitter-dm-button" data-screen-name="@furni">
Message @furni</a>
```

2. Optionally pre-populate message text by customizing the `text` query parameter.

```html theme={null}
<a href="https://x.com/messages/compose?recipient_id=3805104374&text=Hello%20world"
  class="twitter-dm-button" data-screen-name="@furni">
Message @furni</a>
```

3. Asynchronously load the X for Websites JavaScript using our loading snippet. The script will initialize the message button after your page content loads.

### Query parameters

| Parameter      | Description                                                                    |
| -------------- | ------------------------------------------------------------------------------ |
| `recipient_id` | **Required**. The user ID of the X user that will receive the messages.        |
| `text`         | **Optional**. The pre-populated text in the message. Text must be URL encoded. |

### Button customization

#### Size

Add a `data-size` attribute value of `large` to display a larger message button.


# Frequently asked questions
Source: https://docs.x.com/x-for-websites/embedded-posts/faq

An embedded Post comes in two parts: a containing Post information and the JavaScript file from a X server which converts the into a fully-rendered Post.

## A fully-rendered Post does not display on my page

An embedded Post comes in two parts: a `<blockquote>` containing Post information and the JavaScript file from a X server which converts the `<blockquote>` into a fully-rendered Post.

If you see Post text on your page but not a fully-rendered Post it’s possible your CMS or editing interface stripped the `<script>` needed to render the Post.

Try switching to a “text,” “HTML,” or “code editing” mode to directly input the pre-formatted Post information. Rich-text or WYSIWYG editors can misinterpret pasted HTML code, which may interfere with placing a Post on your page.

If you cannot reliably work with HTML in your articles then you or your website team should add the X for Websites JavaScript to your webpage template to interpret any buttons or widgets on the page. Add the following code just before the closing `</body>` element in your website template:

```javascript theme={null}
<script id="twitter-wjs" type="text/javascript" async defer src="//platform.x.com/widgets.js"></script>
```

The JavaScript snippet above loads the X widgets JavaScript if it is not already present on the page. The loaded JavaScript will convert embedded Posts, Embedded Timelines, Post Buttons, and Follow Buttons on your page into interactive widgets and buttons.

## What happens when an author deletes their Post?

The X widgets JavaScript will not display a fully-rendered Post if the Post no longer exists on X. The fallback `<blockquote>` containing Post information will be visible on the page.

## Will embedded Posts adapt to my responsive site?

An embedded Post will adjust to the width of its containing element when inserted into a page. An embedded Post requires a minimum width of 220 pixels and will fill up to 550 horizontal pixels.

## How can I create an Embedded Post of a consistent height?

A basic embedded Post includes Post text up to 140 characters in length, author information, a timestamp, and Post actions. An embedded Post shows the previous Post in a conversation and photos, a video, or a link preview associated with the Post by default. Set conversation and cards parameters to false to limit Post display to just its basic formatting.


# Embedded Post CMS best practices
Source: https://docs.x.com/x-for-websites/embedded-posts/guides/cms-best-practices

An embedded Post adds pieces of the global conversation happening on X to your site, content, and commentary. Sites powered by a CMS or custom software can.

## Overview

An [embedded Post](/x-for-websites/embedded-posts/overview) adds pieces of the global conversation happening on X to your site, content, and commentary. Sites powered by a CMS or custom software can provide deeper integration with X content through site-level display preferences, content macros for cross-platform publishing, oEmbed fallback content, and JavaScript loaders described in this guide. Your extra effort will remove barriers between authors and cited content while integrating our third-party content with your site’s content flows and visual design.

1. [Define site-level theme options](/x-for-websites/embedded-posts/guides/cms-best-practices.html#theme-options)
2. [Define site-level widget options](/x-for-websites/embedded-posts/guides/cms-best-practices.html#widget-options)
3. [Define an embedded Post macro](/x-for-websites/embedded-posts/guides/cms-best-practices.html#macro)
4. [Request fallback markup using oEmbed](/x-for-websites/embedded-posts/guides/cms-best-practices.html#oembed)
5. [Load widget JavaScript using your site’s resource manager](/x-for-websites/embedded-posts/guides/cms-best-practices.html#js-loading)

## Define site-level theme options

Integrate X widgets, including embedded Posts, with your site’s color scheme by including HTML `<meta>` elements `</web/overview/widgets-webpage-properties>` in the `<head>` section of your webpage. Choose a light or dark color theme for Post text and background and customize the iframe border color by adding new markup to your site templates.

```html theme={null}
<meta name="twitter:widgets:theme" content="light">
<meta name="twitter:widgets:border-color" content="#55acee">
```

X for Websites reads the meta values on the page before constructing a new widget; these values can be overridden for individual widgets by passing the appropriate oEmbed parameter.

Adding a X widget options section in your CMS administrative interface helps individual publishers customize content without editing theme files.

## Define site-level widget options

Embedded Posts may contain images, video, link previews, or other Posts in conversations. Your site can specify site-wide preferences for display consistency across all pages, overriding default display options.

Adding an embedded Post options section in your CMS administrative interface helps individual publishers set their preferences for Post content display across the entire site.

## Define an embedded Post macro

A macro added to your site’s editing interface abstracts away the detail of embedding Posts, allowing an author to focus on content. Behind-the-scenes your macro should determine the best content to display in the current rendering environment, such as HTML and JavaScript on a webpage, native views on iOS and Android, or custom elements in AMP or Apple News Format.

The simplest macro is a Post URL added to your article content. You may choose to have a more custom macro to capture additional embedded Post options unique to the article display.

```json theme={null}
[tweet id="611193269532295168" lang="fr"]
```

Verify macro inputs against a set of known embedded Post parameters before passing the option to the X oEmbed endpoint to set author expectations and remove unneeded cruft.

## Request fallback markup using oEmbed

An embedded Post should provide appropriate context when viewed on its own, before additional enhancements provided by X for the current viewer. Request and store HTML markup for the requested Post data by requesting content from the [oEmbed API endpoint](/x-for-websites/oembed-api). Add any custom options passed to your site’s macro, or extracted from the current context, as query parameters in the oEmbed request.

A Post ID is preferred over a Post's web URL: components of the URL such as the associated account’s screen\_name may change; the Post ID is unique to the cited content and will remain the same.

You may choose to omit theme-related options from oEmbed requests if you define these preferences inside your webpage’selements as described above.

The oEmbed response from X's servers adheres to the [oEmbed specification](https://oembed.com/). X's oEmbed response is a “rich” oEmbed type containing HTML markup suitable for use inside existing HTML code.

Sites should cache the HTML returned by the oEmbed API for the suggested cache lifetime specified by the `cache_age` response parameter. Your cache method should incorporate the customization parameters passed to the oEmbed API as these parameters will modify the HTML response.

## Load widget JavaScript using your site’s resource manager

Many sites, frameworks, and CMS systems have specialized CSS and JavaScript resource managers or module loaders tracking dependencies, asynchronous loading, and versioning. Include the remote-hosted widgets.js in your site’s resource loader whenever your site content includes an Embedded Post or other X widget content.

Define a new module definition for the X for Websites JavaScript hosted at `https://platform.x.com/widgets.js`. Define a module ID of “twitter-wjs” to uniquely identify the X JavaScript with the common ID used by [asynchronous loading snippets](/x-for-websites/javascript-api/guides/set-up-x-for-websites) — just in case copy-and-pasted JavaScript makes its way onto the webpage.

Include an `omit_script=true` parameter in your oEmbed request to strip JavaScript from the X response.

Sites loading page fragments containing an embedded Post will need to request a scan for embedded Post content by calling the `twttr.widgets.load` function `</web/javascript/initialization>` after the new content is inserted into the page. Pass one or more DOM elements to the load function to restrict the scan for new content to just the new page fragments to improve site performance.

Sites calling X JavaScript should setup an asynchronous function queue storing functions to be executed in an array accessible at `window.twttr._e`. The X asynchronous loading snippet provides setup of a function queue array with new functions queued by passing a function to `window.twttr.ready`. The X for Websites JavaScript will flush the function queue while first executing its JavaScript.

## Export Post content in syndicated formats

A modern news organization may publish alternate versions of its content formatted for Apple News, Facebook Instant Articles, or AMP clients. A Post cited in an article will need to be described in the markup expected by each format.

### AMP

A Post should be described in an AMP template using the `<amp-twitter>` custom element.

```html theme={null}
<amp-twitter
  data-tweetid="611193269532295168"
  layout="responsive">
```

The AMP webpage will also need to add the `amp-twitter` component’s JavaScript rendering code to the document’s `<head>` to transform the supplied markup into a rendered embedded Post.

```html theme={null}
<script async
  custom-element="amp-twitter"
  src="https://cdn.ampproject.org/v0/amp-twitter-0.1.js">
</script>
```

### Apple News Format

Describe a Post in your article using [the Post component in Apple News Format](https://developer.apple.com/library/ios/documentation/General/Conceptual/Apple_News_Format_Ref/Tweet.html).

```json theme={null}
{
  "role": "tweet",
  "URL": "https://x.com/interior/status/611193269532295168"
}
```

### Facebook Instant Articles Format

Describe a Post contained in your content with [an op-interactive `<figure>` element](https://developers.facebook.com/docs/instant-articles/reference/embeds).

```html theme={null}
<figure class="op-social">
<iframe>
<blockquote class="twitter-tweet">
<p lang="en" dir="ltr">Mama knows best! Mother bear teaches cub how to dig for clams <a href="https://x.com/LakeClarkNPS">@LakeClarkNPS</a> by Sally Jewell <a href="https://x.com/hashtag/Alaska?src=hash">#Alaska</a> <a href="https://x.com/hashtag/nature?src=hash">#nature</a> <a href="http://t.co/1n3vYDJcAW">pic.x.com/1n3vYDJcAW</a></p>
— US Dept of Interior (@Interior) <a href="https://x.com/Interior/status/611193269532295168">June 17, 2015</a>
</blockquote>
<script async
  src="https://platform.x.com/widgets.js">
</script>
</iframe>
<figure>
```


# CSS for embedded Posts
Source: https://docs.x.com/x-for-websites/embedded-posts/guides/css-for-embedded-posts

An embedded Post appears on your page as a with the cited text of a Post; this markup is later interpreted by X for Websites code to render a full embedded.

An embedded Post appears on your page as a `<blockquote>` with the cited text of a Post; this markup is later interpreted by X for Websites code to render a full embedded Post. The `<blockquote>` HTML is available in all rendering environments, including RSS feeds and email updates.

An embedded Post's fallback markup will inherit the CSS rules already applied to `<blockquote>`, `<p>`, and `<a>` HTML elements on your webpage.

Below is some basic CSS to style an embedded Post's `<blockquote>` content in a way that more closely resembles its fully-rendered form.

```css title="Example" expandable lines wrap icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" theme={null}
blockquote.twitter-tweet {
  display: inline-block;
  font-family: "Helvetica Neue", Roboto, "Segoe UI", Calibri, sans-serif;
  font-size: 12px;
  font-weight: bold;
  line-height: 16px;
  border-color: #eee #ddd #bbb;
  border-radius: 5px;
  border-style: solid;
  border-width: 1px;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.15);
  margin: 10px 5px;
  padding: 0 16px 16px 16px;
  max-width: 468px;
}

blockquote.twitter-tweet p {
  font-size: 16px;
  font-weight: normal;
  line-height: 20px;
}

blockquote.twitter-tweet a {
  color: inherit;
  font-weight: normal;
  text-decoration: none;
  outline: 0 none;
}

blockquote.twitter-tweet a:hover,
blockquote.twitter-tweet a:focus {
  text-decoration: underline;
}
```


# Embedded Post JavaScript Factory Function
Source: https://docs.x.com/x-for-websites/embedded-posts/guides/embedded-post-javascript-factory-function

Dynamically insert embedded X Posts into a webpage using the twttr.widgets.createTweet JavaScript factory function from the X for Websites library.

The X for Websites JavaScript library supports dynamic insertion of embedded Posts using the `twttr.widgets.createTweet` function. Pass a Post ID, target parent element, and any custom options.

The code snippets on this page assume `widgets.js` has successfully loaded on your page. Include an asynchronous script loader on your page while initializing `window.twttr` as described in our [JavaScript loader documentation](/x-for-websites/javascript-api/guides/set-up-x-for-websites). All JavaScript code depending on `widgets.js` should execute on or after `twttr.ready`.

| Parameter  | Description                                                                                                                                                     | Example value                          |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `tweetID`  | The numerical ID of the desired Post.                                                                                                                           | `'20'`                                 |
| `targetEl` | DOM node of the desired parent element.                                                                                                                         | `document.getElementById('container')` |
| `options`  | Override default widget options. See [Embedded Post parameter reference](/x-for-websites/embedded-posts/guides/embedded-tweet-parameter-reference) for details. | `{ theme: 'dark' }`                    |

## Example

An element with a DOM ID of `container` exists on the page.

```html theme={null}
<div id="container"></div>
```

The code snippet below will insert [Post ID 20](https://x.com/jack/status/20) into a page inside an element with a unique ID of `container`. The options object specifies a dark theme customization.

```javascript theme={null}
twttr.widgets.createTweet(
  '20',
  document.getElementById('container'),
  {
    theme: 'dark'
  }
);
```

## Promises

The `twttr.widgets.createTweet` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). You can execute code after a widget has been inserted onto your page by passing a callback to the resulting promise’s `then` function.

```javascript theme={null}
twttr.widgets.createTweet(...)
.then( function( el ) {
  console.log('Post added.');
});
```


# Embedded Post parameter reference
Source: https://docs.x.com/x-for-websites/embedded-posts/guides/embedded-tweet-parameter-reference

Reference for embedded Post data-* attributes and JavaScript factory parameters covering theme, width, alignment, conversation, cards, language, and DNT.

An embedded Post supports customization in `data-*` attributes and JavaScript factory functions. This reference document describes parameters used in all formats.

Reference the [oEmbed API](/x-for-websites/oembed-api) to set these parameters as part of an HTML response for a Post ID or URL.

## Parameters

| Parameter      | Description                                                                                                                                                                                                                                 | Example  |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `id`           | The numerical ID of the desired Post.                                                                                                                                                                                                       | `20`     |
| `cards`        | When set to `hidden`, links in a Post are not expanded to photo, video, or link previews.                                                                                                                                                   | `hidden` |
| `conversation` | When set to `none`, only the cited Post will be displayed even if it is in reply to another Post.                                                                                                                                           | `none`   |
| `theme`        | When set to `dark`, displays Post with light text over a dark background.                                                                                                                                                                   | `dark`   |
| `width`        | The maximum width of the rendered Post in whole pixels. This value should be between 250 and 550 pixels.                                                                                                                                    | `325`    |
| `align`        | Float the Post `left`, `right`, or `center` relative to its container. Typically set to allow text or other content to wrap around the Post.                                                                                                | `right`  |
| `lang`         | A supported [X language code](/x-for-websites/supported-languages). Loads text components in the specified language. Note: does not affect the text of the cited Post.                                                                      | `es`     |
| `dnt`          | When set to `true`, the Post and its embedded page on your site are not used for purposes that include [personalized suggestions](https://support.x.com/articles/20169421) and [personalized ads](https://support.x.com/articles/20170405). | `true`   |

### HTML example

```html theme={null}
<blockquote class="twitter-tweet" data-lang="en">
  <p lang="en" dir="ltr">just setting up my twttr</p>&mdash; Jack (@jack) <a href="https://x.com/jack/status/20">March 21, 2006</a>
</blockquote>
```

### JavaScript factory example

```javascript theme={null}
twttr.widgets.createTweet(
  "20",
  document.getElementById("tweet-container"),
  {
    theme: "dark"
  }
);
```

<Note>
  The numeric Post ID should be passed as a string.
</Note>


# Embedded Posts
Source: https://docs.x.com/x-for-websites/embedded-posts/overview

Embed individual Posts on your site using HTML markup, the oEmbed API, or JavaScript factory functions, with theming, alignment, and media display options.

Embedded Posts bring your pick of content from X into your website articles. An embedded Post includes photos, video and cards media created for display on X, and can even stream live video from Periscope. All aspects of X’s display requirements are handled for you by using our tools; author attribution, Post actions, hashtags, mentions, and other key components of the X experience.

An embedded Post consists of two parts: An HTML snippet hosted in your web page, and the X for Websites JavaScript to transform that code into a fully-rendered Post. You can copy embedded Post markup generated from the Post menu on x.com, paste a URL into a supporting CMS, or add a Post to the page programmatically using a JavaScript factory function.

## Embed from x.com

Every Post displayed on x.com includes an embed code to easily copy-and-paste into your webpage. Activate the Post menu and select “Embed Post” to generate markup to include on your webpage:

## Convert Post URLs using oEmbed

Programmatically convert a Post URL into embedded Post markup using the oEmbed API. Make embedding a Post in your CMS or app as simple as pasting a Post URL.

```bash theme={null}
https://publish.x.com/oembed?
  url=https://x.com/Interior/status/463440424141459456
```

Our [CMS best practices guide](/x-for-websites/embedded-posts/guides/cms-best-practices) describes common patterns for sites adding software support for embedded Posts.

## Customize Post display

Customize an embedded Post for your site’s visual design and display preferences by including extra parameters in your embedded Post HTML.

### Match your site’s color scheme

An embedded Post supports light and dark color themes. Customize X widgets [at the page-level with `<meta>` elements](/x-for-websites/webpage-properties) or `add data-*` attributes to individual generated `<blockquote>` elements.

View our [embedded Post reference documentation](/x-for-websites/embedded-posts/guides/embedded-tweet-parameter-reference) for a full list of embedded Post options.

### Don’t show previous Post in conversation thread

A Post may be in reply to another Post. By default, we include a summary of the previous Post in the conversation to provide context.

Set an oEmbed query parameter of `hide_thread=true` or add a `data-conversation="none"` attribute to the resulting `<blockquote>` element to prevent the display of a parent Post.

### Hide photos, videos, and Cards

A Post may include a photo, video, or link to or other content supporting a [Card](https://dev.x.com/cards/overview). By default, this media is displayed in embedded Posts. You can hide this media if editorially desired.

Set an oEmbed query parameter of `hide_media=true` or add a `data-cards="hidden"` attribute to the resulting `<blockquote>` element to prevent expanded content display.

### Customize Alignment

An embedded Post is aligned left by default. The Post can be center or right aligned if preferred using the align customization. While historically CSS provides numerous hacks for centering content on a web page, this is the recommended and official supported method.

## Render a Post with JavaScript

Our widget JavaScript scans the DOM on execution, converting `blockquote.twitter-tweet` elements into fully-rendered embedded Posts based on element content.

If dynamically inserting new content into a page, pass the new document fragment to [twttr.widgets.load()](/x-for-websites/javascript-api/guides/scripting-loading-and-initialization) to initialize embedded Post content.

To directly render an embedded Post at runtime use the [twttr.widgets.createTweet()](/x-for-websites/embedded-posts/guides/embedded-post-javascript-factory-function) function.


# Frequently asked questions
Source: https://docs.x.com/x-for-websites/follow-button/faqs-follow-button

Frequently asked questions about the X Follow button covering its dimensions, sizing behavior, screen_name handling, and follower count display options.

## What are the dimensions of the follow button?

The follow button is 20 pixels in height. Its width will vary depending on the language you have chosen (or the language of the viewer), the length of the specified `screen_name`, number of followers when `show_count` is active, etc. We recommend you make room for the `screen_name` value, and `show_count` value if you choose to display it.

Note if you use the JavaScript version of the Follow Button, you can specify the width using the `data-width` attribute. If you are using the iframe version you can use the `style` property.


# Follow Button JavaScript Factory Function
Source: https://docs.x.com/x-for-websites/follow-button/guides/javascript-factory-function-follow-button

Use twttr.widgets.createFollowButton to dynamically insert a Follow button on your page with a username, target element, custom options, and a promise callback.

The X for Websites JavaScript library supports dynamic insertion of a follow button using the `twttr.widgets.createFollowButton` function. Pass X username, target parent element, and any custom options.

The code snippets on this page assume `widgets.js` has successfully loaded on your page. Include an asynchronous script loader on your page while initializing `window.twttr` as described in our [JavaScript loader documentation](/x-for-websites/javascript-api/guides/set-up-x-for-websites). All JavaScript code depending on `widgets.js` should execute on or after `twttr.ready`.

## Arguments

| Parameter  | Description                            | Example value                          |
| ---------- | -------------------------------------- | -------------------------------------- |
| `username` | A X username                           | `'XDevelopers'`                        |
| `targetEl` | DOM node of the desired parent element | `document.getElementById('container')` |
| `options`  | Override default widget options        | `{ size: 'large' }`                    |

## Example

An element with a DOM ID of `container` exists on the page.

```html theme={null}
<div id="container"></div>
```

The code snippet below will create a new Follow button for the X username “XDevelopers” inserted into a page inside an element with a unique ID of `container`.

```javascript theme={null}
twttr.widgets.createFollowButton(
  'XDevelopers',
  document.getElementById('container'),
  {
    size: 'large'
  }
);
```

## Promises

The `twttr.widgets.createFollowButton` function returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). You can execute code after a widget has been inserted onto your page by passing a callback to the resulting promise’s `then` function.

```javascript theme={null}
twttr.widgets.createFollowButton(...)
.then( function( el ) {
  console.log('Follow button added.');
});
```


# Parameters
Source: https://docs.x.com/x-for-websites/follow-button/guides/parameter-reference-follow-button

A Follow button may be customized from its default settings by specifying parameter overrides. Documentation for the X developer platform covering parameter.

A Follow button may be customized from its default settings by specifying parameter overrides.

| Parameter          | Description                                                                                                                                                                                                                                   | Example       |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `screen_name`      | The X username to be followed. Automatically extracted from the anchor element’s `href` attribute when using JavaScript-enhanced button markup.                                                                                               | `XDevelopers` |
| `show_screen_name` | Set to `false` to hide the username of the specified account.                                                                                                                                                                                 | `false`       |
| `size`             | Set to `large` to display a larger button.                                                                                                                                                                                                    | `large`       |
| `lang`             | A supported [X language code](/x-for-websites/supported-languages).                                                                                                                                                                           | `es`          |
| `dnt`              | When set to `true`, the button and its embedded page on your site are not used for purposes that include [personalized suggestions](https://support.x.com/articles/20169421) and [personalized ads](https://support.x.com/articles/20170405). | `true`        |

## HTML example

```html theme={null}
<a class="twitter-follow-button"
  href="https://x.com/XDevelopers"
  data-show-screen-name="false"
  data-size="large"
>
Follow @XDevelopers
</a>
```

## JavaScript example

```javascript theme={null}
twttr.widgets.createFollowButton(
  "XDevelopers",
  document.getElementById("container"),
  {
    showScreenName: "false",
    size: "large"
  }
);
```


# Follow Button Web Intent
Source: https://docs.x.com/x-for-websites/follow-button/guides/web-intent-follow-button

Web Intents display X actions optimized for display in a small browser window. A website may link to a follow web intent through a simple link on any.

[Web Intents](/x-for-websites/web-intents/overview) display X actions optimized for display in a small browser window. A website may link to a follow web intent through a simple link on any website. X for Websites JavaScript widgets use the follow web intent to prompt viewers to follow an account.

A follow Web Intent window features an inline login form for logged-out X users.

The user will follow the account on successful login through the inline follow web intent login form. The follow status is confirmed by the “Following” button displayed in the web intent window.

We recommend rendering a Web Intent child window dimensions of at least 550 pixels wide and 420 pixels high.

## Web Intent URL

```
https://x.com/intent/follow
```

## Query parameters

A follow Web Intent must reference a X account by `screen_name` or `user_id`. A `screen_name` may change; we recommend using `user_id` whenever possible.

| Parameter     | Description                                                              | Example value |
| ------------- | ------------------------------------------------------------------------ | ------------- |
| `screen_name` | The X username of the account you would like the viewer to follow        | `xdevelopers` |
| `user_id`     | The X user identifier of the account you would like the viewer to follow | `2244994945`  |


# Follow button
Source: https://docs.x.com/x-for-websites/follow-button/overview

Add an X Follow button to your website with HTML markup or publish.x.com, customize size and screen name display, and load it with widgets.js.

The Follow button is a small button displayed on your websites to help users easily follow a X account. A Follow button consists of two parts: a link to a [follow web intent](/x-for-websites/follow-button/overview) page on x.com and the X for Websites JavaScript to transform the link into our recognizable Follow button.

## How to add a Follow button to your website

The [publish.x.com](https://publish.x.com) website includes a simple tool to generate the embed for a Follow button to copy-and-paste into your website template. Just enter a @screenName to get started.

### Manually

1. Create an anchor element with a `twitter-follow-button` class name. Set the `href` attribute value pointing to a X profile URL.

```html theme={null}
<a class="twitter-follow-button"
  href="https://x.com/XDevelopers">
Follow @XDevelopers</a>
```

2. Customize Follow button parameters using `data-*` attributes.

```html theme={null}
<a class="twitter-follow-button"
  href="https://x.com/XDevelopers"
  data-size="large">
Follow @XDevelopers</a>
```

3. Asynchronously load the X for Websites JavaScript using our loading snippet. The script will initialize the Follow button after your page content loads.

## Button customization

### Hide username

Hide the username from the displayed Follow button by setting a `data-show-screen-name` attribute value of `false`.

### Large button style

Add a `data-size` attribute value of `large` to display a larger Follow button.


# Scripting: Events
Source: https://docs.x.com/x-for-websites/javascript-api/guides/javascript-api

Bind callbacks to X for Websites widget events such as loaded, rendered, tweet, follow, retweet, like, and click using twttr.events.bind for analytics.

The X for Websites JavaScript fires events on initialization and after a viewer interacts with a widget. Enhance your application and analytics by tapping into widget events.

Note that Web Intent events fire when the interaction occurs, not after the action completes.

Bind a X widget event in your JavaScript code by registering a callback function with `twttr.events.bind`.

```javascript theme={null}
twttr.events.bind(
  'click',
  function (ev) {
    console.log(ev);
  }
);
```

## The Intent Event Object

When a detectable action occurs within a Web Intent or widget, an object representing the event is passed to your JavaScript callback. Intent Event objects include the following data:

### Intent event object properties

| Property | Data Type     | Description                                                                                                                                                                                                                                                                    |
| -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `target` | `HTMLElement` | The DOM node where the widget is instantiated. Most likely an iframe, but may also be the original embed code element if the widget failed to initialize, or another sandboxed element. Use this value to differentiate between different intents or buttons on the same page. |
| `region` | `String`      | Extended detail indicating where in a widget the event originated. For example, button or count components of Post button or Follow button integrations, or Post actions within an embedded Post.                                                                              |
| `data`   | `Object`      | Key/value pairs relevant to the event.                                                                                                                                                                                                                                         |

## Waiting for asynchronous resources

Loading the widgets.js file asynchronously will require you to wait before binding events: the functions you are calling do not yet exist. You will need to wrap your event bindings in a callback function such as the twttr.ready asynchronous function queue which will be invoked once everything has loaded. All event examples below assume you have wrapped those event bindings in this callback.

```javascript theme={null}
twttr.ready(
  function (twttr) {
    // bind events here
  }
);
```

## Available Events

### loaded

Occurs after `twttr.widgets.load` has initialized widgets in a page. Includes an array of references to the newly created widget nodes.

```javascript theme={null}
twttr.events.bind(
  'loaded',
  function (event) {
    event.widgets.forEach(function (widget) {
      console.log("Created widget", widget.id);
    });
  }
);
```

### rendered

Occurs after an individual widget in a page is rendered. Includes a reference to the newly created widget node. Occurs at the same time as `loaded`, but for each individual widget. Also triggered when creating a widget with a factory function.

```javascript theme={null}
twttr.events.bind(
  'rendered',
  function (event) {
    console.log("Created widget", event.target.id);
  }
);
```

### tweet

This event will be triggered when the user clicks a Post Web Intent.

Includes a Post in reply to an [embedded Post](/x-for-websites/timelines/overview) or a Post displayed in an [embedded Timeline](/x-for-websites/timelines/overview).

```javascript theme={null}
twttr.events.bind(
  'tweet',
  function (event) {
    // Do something there
  }
);
```

### follow

This event will populate the followed `user_id` or `screen_name` in the event object’s data argument, depending on the parameters you provided in the web intent.

```javascript theme={null}
twttr.events.bind(
  'follow',
  function (event) {
    var followedUserId = event.data.user_id;
    var followedScreenName = event.data.screen_name;
  }
);
```

### retweet

This event will populate the original Post that was reposted's `source_tweet_id` in the event object’s data argument.

```javascript theme={null}
twttr.events.bind(
  'retweet',
  function(event) {
    var repostedPostId = event.data.source_tweet_id;
  }
);
```

### like

This event will populate the liked `tweet_id` in the event object’s data argument.

```javascript theme={null}
twttr.events.bind(
  'like',
  function(event) {
    var likedPostId = event.data.tweet_id;
  }
);
```

### click

Receive an event when the user invokes a Web Intent from within an embedded widget.

## Example: Detecting events for web analytics

It’s easy to capture these events and pipe them to your web analytics solution. Please note that you’ll need to be using HTTP or HTTPs protocols on the hosting page for these events.

```javascript title="Example" expandable lines wrap icon="square-js" theme={null}
// Log any kind of Web Intent event to Google Analytics
// Category: "twitter_web_intents"
// Action: Intent Event Type
// Label: Identifier for action taken: tweet_id, screen_name/user_id, click region

// First, load the widgets.js file asynchronously
window.twttr = (function(d, s, id) {
  var js, fjs = d.getElementsByTagName(s)[0],
    t = window.twttr || {};
  if (d.getElementById(id)) return;
  js = d.createElement(s);
  js.id = id;
  js.src = "https://platform.x.com/widgets.js";
  fjs.parentNode.insertBefore(js, fjs);

  t._e = [];
  t.ready = function(f) {
    t._e.push(f);
  };

  return t;
}(document, "script", "twitter-wjs"));

// Define our custom event handlers
function clickEventToAnalytics (intentEvent) {
  if (!intentEvent) return;
  var label = intentEvent.region;
  pageTracker._trackEvent('twitter_web_intents', intentEvent.type, label);
}

function postIntentToAnalytics (intentEvent) {
  if (!intentEvent) return;
  var label = "tweet";
  pageTracker._trackEvent(
    'twitter_web_intents',
    intentEvent.type,
    label
  );
}

function likeIntentToAnalytics (intentEvent) {
  postIntentToAnalytics(intentEvent);
}

function repostIntentToAnalytics (intentEvent) {
  if (!intentEvent) return;
  var label = intentEvent.data.source_tweet_id;
  pageTracker._trackEvent(
    'twitter_web_intents',
    intentEvent.type,
    label
  );
}

function followIntentToAnalytics (intentEvent) {
  if (!intentEvent) return;
  var label = intentEvent.data.user_id + " (" + intentEvent.data.screen_name + ")";
  pageTracker._trackEvent(
    'twitter_web_intents',
    intentEvent.type,
    label
  );
}

// Wait for the asynchronous resources to load
twttr.ready(function (twttr) {
  // Now bind our custom intent events
  twttr.events.bind('click', clickEventToAnalytics);
  twttr.events.bind('tweet', postIntentToAnalytics);
  twttr.events.bind('retweet', repostIntentToAnalytics);
  twttr.events.bind('like', likeIntentToAnalytics);
  twttr.events.bind('follow', followIntentToAnalytics);
});
```

## Supplemental events resources and examples

* [Google Analytics Event Tracking Guide](http://code.google.com/apis/analytics/docs/tracking/eventTrackerGuide.html)
* [Google Analytics SocialWidgetTracker plugin](https://github.com/googleanalytics/autotrack/blob/master/lib/plugins/social-widget-tracker.js)
* [X Intent Events with Google Analytics using \_gaq.push();](http://null-uk.com/55090968) by [@nulluk](http://x.com/intent/user?screen_name=nulluk)
* [An optimized approach to Google Analytics integration](https://gist.github.com/1004702) by [@yahel](https://x.com/yahel)

These functions make it possible to integrate X user’s content into your site dynamically in a JavaScript application, and integrate user interactions into your own application experience.

Please ask questions and share your code and examples in the [developer forum](https://devcommunity.x.com/). You may also refer to the main [X for Websites documentation](/x-for-websites/overview).


# Scripting: Factory Functions
Source: https://docs.x.com/x-for-websites/javascript-api/guides/scripting-factory-functions

If you’re integrating your site with X using X for Websites and Web Intents, you can dynamically generate widgets using JavaScript functions.

If you’re integrating your site with X using [X for Websites](/x-for-websites/overview) and [Web Intents](/x-for-websites/web-intents/overview), you can dynamically generate widgets using JavaScript functions.

X for Websites products—Post buttons, Follow buttons, embedded Posts and timelines—are all loaded using a JavaScript utility named `widgets-js`. When adding an X widget to your page, this JavaScript file is included in the HTML embed code, or you can directly include `https://platform.x.com/widgets.js` in your page. (See the [X for Websites set-up documentation](/x-for-websites/javascript-api/guides/set-up-x-for-websites) for a recommended code snippet.)

By default, `widgets-js` will find mark-up in a page and convert basic, functional mark-up into rich interactive widgets. In addition, there are a number of functions of `widgets-js` that allow you to work with X content dynamically:

## Creating widgets at runtime with factory functions

Widgets can be generated at runtime, without requiring an HTML embed code. A set of factory functions can generate any widget type:

* [twttr.widgets.createShareButton](/x-for-websites/post-button/guides/javascript-factory-function)
* [twttr.widgets.createFollowButton](/x-for-websites/follow-button/guides/javascript-factory-function-follow-button)
* [twttr.widgets.createHashtagButton](/x-for-websites/post-button/guides/hashtag-button)
* [twttr.widgets.createMentionButton](/x-for-websites/post-button/guides/mention-button)
* [twttr.widgets.createTimeline](/x-for-websites/timelines/overview)
* [twttr.widgets.createTweet](/x-for-websites/post-button/overview)

### Buttons

`createShareButton`, `createFollowButton`, `createHashtagButton`, and `createMentionButton` take similar arguments.

#### Primary argument

The first argument is required, and is unique to the button type. Provide a string representing one of:

* `url`: The URL to be shared.
* `screen_name`: The screen\_name of a user to be followed, or mentioned.
* `hashtag`: Hashtag to be posted and displayed on the button.

#### Additional Arguments:

* `target`: **Required**. The element in which to render the widget.
* `options`: *Optional*. An object hash of additional options to configure the widget.

<Note>
  Widgets usually render as iframe elements. When an iframe is moved within the DOM the browser will reload its content. For buttons this can waste bandwidth, while for Posts and timelines this will cause dynamically injected content to be lost. Use the target argument to render widgets into their final location in a page. If you need to delay the display of a widget, use CSS to position the widget off-screen until needed.
</Note>

Every `create` function returns a `Promise`. You can execute code after a widget has been created by passing a callback to:

```javascript theme={null}
twttr.widgets.createFoo()
  .then(function (element) {
    console.log("Widget created.")
  });
```

When fulfilled, the promise will pass a reference to a newly created widget element to the chained callback.

### Examples

Create a share button for a URL:

```javascript theme={null}
twttr.widgets.createShareButton(
  '/',
  document.getElementById('new-button'),
  {
    count: 'none',
    text: 'Sharing a URL using the Post Button'
  }).then(function (el) {
    console.log("Button created.")
  });
```

Create a Follow button for a user:

```javascript theme={null}
twttr.widgets.createFollowButton(
  'endform',
  document.getElementById('new-button'),
  {
    size: 'large'
  }).then(function (el) {
    console.log("Follow button created.")
  });
```

### Options

Additional configuration and options can be passed to the factory functions, as in the above examples.

**Additional configuration for all widgets**

| Option    | Values                                           | Default     | Notes                                                                                                                                                                                                                                        |
| --------- | ------------------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lang`    | An ISO 639-1 language code                       | `en`        | The language in which to render a widget, if supported (see the [Translation Center](http://translate.x.com/)).                                                                                                                              |
| `dnt`     | `true`, `false`                                  | `false`     | When set to `true`, the embed and its embedded page on your site are not used for purposes that include [personalized suggestions](https://support.x.com/articles/20169421) and [personalized ads](https://support.x.com/articles/20170405). |
| `related` | Any comma-separated list of valid X screen names | `Undefined` | A list of X screen names to be suggested for following after a Post or Post action is posted.                                                                                                                                                |
| `via`     | Any valid X screen name                          | `Undefined` | An X user mentioned in the default Post text as `via@user` where appropriate.                                                                                                                                                                |

**Additional configuration options for button widgets**

| Option  | Values            | Default                                                                               | Notes                                                                                               |
| ------- | ----------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `align` | `left`, `right`   | Locale dependent (`left` or `right`, depending on the text direction of the language) | The alignment of the button within an iframe; use this to ensure flush layout when aligning buttons |
| `size`  | `medium`, `large` | `medium`                                                                              |                                                                                                     |

**Post button additional options**

| Option     | Values                             | Default     | Notes                                                                     |
| ---------- | ---------------------------------- | ----------- | ------------------------------------------------------------------------- |
| `text`     | Any string                         | `Undefined` | The default, highlighted text a user sees in the Post web intent          |
| `hashtags` | A comma-separated list of hashtags | `Undefined` | A list of hashtags to be appended to default Post text where appropriate. |

### Posts

`createTweet` takes the ID for a Post, and then the same additional arguments as for buttons.

#### Arguments

* `tweetId`: The ID of a Post to be rendered. (This should be provided as a `String`, since X IDs are generated from 64-bit integers, and JavaScript integers are limited to 53 bits.)
* `target`: **Required**. The element in which to render the widget.
* `options`: *Optional*. A hash of additional options to configure the widget.

#### Examples

Create an embedded Post for [a Post from the US Department of Interior](https://x.com/Interior/status/511181794914627584):

```javascript theme={null}
twttr.widgets.createTweet(
  '511181794914627584',
  document.getElementById('first-tweet'),
  {
    align: 'left'
  })
  .then(function (el) {
    console.log("Post displayed.")
  });
```

### Options

| Option         | Values                    | Default                              | Notes                                                                                                                                                     |
| -------------- | ------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `conversation` | `none`, `all`             | `all`                                | Posts in response to another Post will display a compact version of the previous Post by default. Use `none` to hide the parent Post in the conversation. |
| `cards`        | `hidden`, `visible`       | `visible`                            | Hide photos, videos, and link previews powered by [Cards](https://dev.x.com/cards).                                                                       |
| `width`        | Positive integer          | `auto` (derived from container size) | Set the maximum width of the embedded Post                                                                                                                |
| `align`        | `left`, `right`, `center` | `Undefined`                          | Float the embedded Post to the left or right so that text wraps around it, or align center so it floats in the middle of a paragraph                      |
| `theme`        | `dark`, `light`           | `light`                              | Toggle the default color scheme of the embedded Post                                                                                                      |

### Timelines

`createTimeline` takes the data source definition for a timeline. Additional arguments are consistent with embedded Posts.

#### Arguments

* **data source**: *Required* The data source definition object for the content to be displayed in the widget. May be a widget ID string for a legacy widget.
* `target`: **Required**. The element in which to render the widget.
* `options`: *Optional*. A hash of additional options to configure the widget.

#### Examples

Create a timeline widget:

```javascript title="Example" lines wrap icon="square-js" theme={null}
twttr.widgets.createTimeline(
  {
    sourceType: 'profile',
    screenName: 'xdevelopers'
  },
  document.getElementById('timeline'),
  {
    width: '450',
    height: '700',
    related: 'xdevelopers,api'
  }).then(function (el) {
    console.log('Embedded a timeline.')
  });
```

#### Data Source

The data source definition describes what content will hydrate the embedded timeline. There are several types of data sources: profile; list; URL; widget configuration.

##### Profile

To power an embedded timeline with Posts from an individual user use a `profile` data source. To do so, set `sourceType` to `profile` and set one of `screenName` or `userId`.

| Option       | Values           |
| ------------ | ---------------- |
| `sourceType` | `profile`        |
| `screenName` | Valid X username |
| `userId`     | Valid X user ID  |

```javascript theme={null}
twttr.widgets.createTimeline(
  {
    sourceType: 'profile',
    screenName: 'xdevelopers'
  },
  document.getElementById('container')
);
```

##### List

To power an embedded timeline with an X list use a `list` data source. Set `sourceType` to `list` and set both `ownerScreenName` and `slug`, or set an `id`.

| Option            | Values                           | Notes                       |
| ----------------- | -------------------------------- | --------------------------- |
| `sourceType`      | `list`                           |                             |
| `ownerScreenName` | Valid X username                 | Used with `slug`            |
| `slug`            | The string identifier for a list | Used with `ownerScreenName` |
| `id`              | Valid X list ID                  |                             |

```javascript theme={null}
twttr.widgets.createTimeline(
  {
    sourceType: 'list',
    ownerScreenName: 'x',
    slug: 'official-x-accts'
  },
  document.getElementById('container')
);
```

##### URL

To power an embedded timeline with X content represented by a URL use a `url` data source. Supported content includes profiles and lists.

| Option       | Values                               |
| ------------ | ------------------------------------ |
| `sourceType` | `url`                                |
| `url`        | Absolute URL of an X profile or list |

```javascript theme={null}
twttr.widgets.createTimeline(
  {
    sourceType: 'url',
    url: 'https://x.com/xdevelopers'
  },
  document.getElementById('container')
);
```

### Options

All the parameters described above for all widgets and for embedded Posts also apply to embedded timelines.

| Option        | Values                                                            | Default         | Notes                                                                                                                                         |
| ------------- | ----------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `chrome`      | `noheader`, `nofooter`, `noborders`, `transparent`, `noscrollbar` | `Undefined`     | Toggle the display of design elements in the widget. This parameter is a space-separated list of values.                                      |
| `height`      | Positive integer                                                  | `600`           | Set a fixed height of the embedded widget                                                                                                     |
| `tweetLimit`  | Range: `1`-`20`                                                   | `Undefined`     | Render a timeline statically, displaying only n number of Posts.                                                                              |
| `borderColor` | Hexadecimal color                                                 | Varies by theme | Adjust the color of borders inside the widget.                                                                                                |
| `ariaPolite`  | `polite`, `assertive`, `rude`                                     | `polite`        | Apply the specified aria-polite behavior to the rendered timeline. New Posts may be added to the top of a timeline, affecting screen readers. |

For more information on the options for customizing embedded Timelines refer to [Embedded Timelines](/x-for-websites/timelines/overview).

These functions make it possible to integrate X user’s content into your site dynamically in a JavaScript application, and integrate user interactions into your own application experience.

Please ask questions and share your code and examples in the [developer forum](https://devcommunity.x.com/). You may also refer to the main [X for Websites documentation](/x-for-websites/javascript-api/guides/set-up-x-for-websites).


# Scripting: Loading and Initialization
Source: https://docs.x.com/x-for-websites/javascript-api/guides/scripting-loading-and-initialization

Use twttr.widgets.load to scan the DOM and initialize new X for Websites buttons or widgets added dynamically through lazy loading or pushState navigation.

## Initializing embedded content after a page has loaded

Most X for Websites integrations will be well served by the recommended embed code found in the [set-up documentation](/x-for-websites/javascript-api/guides/set-up-x-for-websites), but you may want to optimize how and when the Twitter for Websites JavaScript widgets scans the page DOM to discover new HTML elements eligible for enhancement into buttons or widgets.

If content is dynamically inserted into a page (such as lazy-loading content or using a `pushState` technique to navigate between articles) it’s necessary to parse new buttons and widgets using the `twttr.widgets.load()` function.

```javascript theme={null}
twttr.widgets.load()
```

Called without argument, `widgets-js` will search the entire `document.body` DOM tree for uninitialized widgets. For better performance, pass an `HTMLElement` object to restrict the search only to children of the element.

Example:

```javascript theme={null}
twttr.widgets.load(
  document.getElementById("container")
);
```


# Set up X for Websites
Source: https://docs.x.com/x-for-websites/javascript-api/guides/set-up-x-for-websites

Set up X for Websites by adding the widgets.js asynchronous loader snippet to your site template for faster widget rendering and reliable embed support.

The easiest way to create a X for Websites widget — a Post button, Follow button, embedded Post or timeline — is to use our configuration tools at [publish.x.com](https://publish.x.com) then copy and paste the generated HTML code into the template or widget area for your site.

* [Generate markup for a Post or Follow button](https://publish.x.com)
* [Generate markup for an embedded Post or timeline](https://publish.x.com)

## For best performance and reliability, include the widgets.js script in your template

Include the X for Websites JavaScript once in your page template for optimal web page performance and to enable tracking of [X widget JavaScript events](/x-for-websites/javascript-api/guides/javascript-api).

If your site is using multiple widgets you can set up X widgets in your pages once, which will make your site faster, and widgets such as embedded Posts will be more reliable for authors when using content management systems.

```html title="Example" lines wrap icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" theme={null}
<script>window.twttr = (function(d, s, id) {
  var js, fjs = d.getElementsByTagName(s)[0],
    t = window.twttr || {};
  if (d.getElementById(id)) return t;
  js = d.createElement(s);
  js.id = id;
  js.src = "https://platform.x.com/widgets.js";
  fjs.parentNode.insertBefore(js, fjs);

  t._e = [];
  t.ready = function(f) {
    t._e.push(f);
  };

  return t;
}(document, "script", "twitter-wjs"));</script>
```

The above snippet optimizes loading by:

1. Assign an HTML element ID of `twitter-wjs` to easily identify if the JavaScript file already exists on the page. Exit early if the ID already exists.
2. Asynchronously load the Twitter for Websites JavaScript.
3. Initialize an asynchronous function queue to hold dependent functions until the script is available.

Include this snippet before any other JavaScript on your page which may depend on the `twttr.ready` asynchronous function queue.

## Ignore script tags from embeds

If you include the X JavaScript loader on every page you do not need to include the `<script>` element generated by a button configurator, embedded Post, or embedded Timeline tool. You can delete the extra `<script>` HTML from generated markup.

If you use the [oEmbed API](/x-for-websites/oembed-api) to include Posts in your content, you can generate embed codes that don’t include the `<script>` element by passing `omit_script=true` in the query string.


# JavaScript Interfaces for X for Websites
Source: https://docs.x.com/x-for-websites/javascript-api/overview

Overview of the X for Websites JavaScript API for enhancing embedded Posts, timelines, and Web Intents on your site with dynamic widget loading and events.

If you’re integrating your site with X using [X for Websites](/x-for-websites/overview) and [Web Intents](/x-for-websites/web-intents/overview), you can enhance your application using JavaScript. By default, `widgets-js` will find markup in a page and convert basic, functional mark-up into rich interactive widgets. In addition, there are a number of functions of `widgets-js` that allow developers to work with X content dynamically, after the page has loaded.

This documentation has been broken into chapters:

* [Setting up X for Websites](/x-for-websites/javascript-api/guides/set-up-x-for-websites)
* [Controlling Loading and Initialization of Widgets](/x-for-websites/javascript-api/guides/scripting-loading-and-initialization)
* [Factory functions to generate widgets](/x-for-websites/javascript-api/guides/scripting-factory-functions)
* [Events from widgets and Web Intents](/x-for-websites/javascript-api/guides/javascript-api)

These functions make it possible to integrate a X user’s content into your site dynamically in a JavaScript application, and integrate user interactions into your own application experience.

Please ask questions and share your code and examples in the [developer forum](https://devcommunity.x.com/). You may also refer to the main [X for Websites documentation](/x-for-websites/javascript-api/guides/set-up-x-for-websites).


# Browser sign in flow
Source: https://docs.x.com/x-for-websites/log-in-with-x/guides/browser-sign-in-flow

How the Sign in with X browser flow works on desktop and mobile, redirecting users to x.com for authorization before returning to your application URL.

The browser sign in flow is appropriate for websites and applications which are able to open or embed a web browser. At a very high level:

* The application renders a “Sign in with X” link or button.
* The user clicks the sign in button.
* The current web browser is redirected to X (or a new browser is opened and directed to X).
* The user completes a login and authorization step at X if needed.
* X redirects back to an URL under the application’s control, passing authorization information for the user.

X keeps track of the authorizations, so for users already signed in to x.com who have authorized the application, no UI is shown - instead, they are automatically redirected back to the application.

## Desktop flow

To demonstrate the flows, pretend the website pictured to the right (“The greatest website ever created”) has implemented this API, as shown by the Sign in with X button on the landing page.

When the user clicks the Sign in button, the page they see depends on whether they are signed in and whether they have previously allowed the application to access their account.

When **the user is signed in to x.com but has not granted access**, a list of requested permissions, along with Sign In and Cancel buttons are shown.

When **the user is not signed in to x.com** input fields for a username and password will be shown. Note that even if the user has already granted access to the application, the list of permissions will still be shown.

After the user inputs valid credentials (if needed) and clicks “Sign In”, X will redirect the user to the website which started the sign in flow.

In the case where **the user is already signed in to x.com and has granted access to the website**, this redirect happens immediately.

To learn how to implement this sign in flow, read [Implementing Sign in with X](/x-for-websites/log-in-with-x/guides/implementing-sign-in-with-x).


# Implementing Sign in with X
Source: https://docs.x.com/x-for-websites/log-in-with-x/guides/implementing-sign-in-with-x

The browser implementation of Sign in with X is based on OAuth. This page demonstrates the requests needed to obtain an access token for the sign in flow.

## Overview

The [browser](/x-for-websites/log-in-with-x/guides/browser-sign-in-flow) implementation of [Sign in with X](/x-for-websites/log-in-with-x/overview) is based on OAuth. This page demonstrates the requests needed to obtain an access token for the sign in flow.

To use the “Sign in with X flow, please go to your X app settings and ensure that the “Allow this app to be used to Sign in with X?” option is enabled.

This page assumes that the reader knows how to sign requests using the OAuth 1.0a protocol. If you want to know how to sign a request, read the [Authorizing a request](/fundamentals/authentication/oauth-1-0a/authorizing-a-request) page.

If you want to check the signing of the requests on this page, the consumer secret used is:

```
L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
```

This value has been disabled and will not work for real requests.

## Step 1: Obtaining a request token

To start a sign-in flow, your X app must obtain a request token by sending a signed message to [POST oauth / request\_token](/fundamentals/authentication/api-reference). The only unique parameter in this request is `oauth_callback`, which must be a URL-encoded version of the URL you wish your user to be redirected to when they complete step 2. The remaining parameters are added by the OAuth signing process.

<Note>
  **Please note** - Any callback URL that you use with the [POST oauth / request\_token](/fundamentals/authentication/api-reference) endpoint will have to be whitelisted within the X app settings in the developer console.
</Note>

### Example request (Authorization header has been wrapped):

```
POST /oauth/request_token HTTP/1.1
User-Agent: themattharris' HTTP Client
Host: api.x.com
Accept: */*
Authorization:
        OAuth oauth_callback="http%3A%2F%2Flocalhost%2Fsign-in-with-x%2F",
              oauth_consumer_key="cChZNFj6T5R0TigYB9yd1w",
              oauth_nonce="ea9ec8429b68d6b77cd5600adbbb0456",
              oauth_signature="F1Li3tvehgcraF8DMJ7OyxO4w9Y%3D",
              oauth_signature_method="HMAC-SHA1",
              oauth_timestamp="1318467427",
              oauth_version="1.0"
```

Your app should examine the HTTP status of the response. Any value other than `200` indicates a failure. The body of the response will contain the `oauth_token`, `oauth_token_secret`, and `oauth_callback_confirmed` parameters. Your app should verify that `oauth_callback_confirmed` is true and store the other two values for the next steps.

### Example response (response body has been wrapped):

```
HTTP/1.1 200 OK
Date: Thu, 13 Oct 2011 00:57:06 GMT
Status: 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 146
Pragma: no-cache
Expires: Tue, 31 Mar 1981 05:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0
Vary: Accept-Encoding
Server: tfe

oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0&
oauth_token_secret=veNRnAWe6inFuo8o2u8SLLZLjolYDmDP7SzL0YfYI&
oauth_callback_confirmed=true
```

## Step 2: Redirecting the user

The next step is to direct the user to X so that they may complete the appropriate flow, as described in [Browser sign-in flow](/x-for-websites/log-in-with-x/guides/browser-sign-in-flow). Direct the user to [GET oauth / authenticate](/fundamentals/authentication/api-reference), and the request token obtained in step 1 should be passed as the `oauth_token` parameter.

The most seamless way for a website to implement this would be to issue an HTTP 302 redirect as the response to the original “sign in” request. Mobile and desktop apps should open a new browser window or direct to the URL via an embedded web view.

### Example URL to redirect to:

```
https://api.x.com/oauth/authenticate?oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0
```

The sign in endpoint will behave in one of three ways depending on the user’s status:

1. **Signed in and approved**: If the user is signed in on x.com and has already approved the calling application, they will be immediately authenticated and returned to the callback URL with a valid OAuth request token. The redirect to x.com is not obvious to the user.
2. **Signed in but not approved**: If the user is signed in to x.com but has not approved the calling application, a request to share access with the calling application will be shown. After accepting the authorization request, the user will be redirected to the callback URL with a valid OAuth request token.
3. **Not signed in**: If the user is not signed in on x.com, they will be prompted to enter their credentials and grant access for the application to access their information on the same screen. Once signed in, the user will be returned to the callback URL with a valid OAuth request token.

Upon a successful authentication, your `callback_url` would receive a request containing the `oauth_token` and `oauth_verifier` parameters. Your application should verify that the token matches the request token received in step 1.

### Request from client’s redirect (querystring parameters wrapped):

```
GET /sign-in-with-x/?
        oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0&
        oauth_verifier=uw7NjWHT6OJ1MpJOXsHfNxoAhPKpgI8BlYDhxEjIBY HTTP/1.1
Host: localhost
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.5 (KHTML, like Gecko) Chrome/16.0.891.1 Safari/535.5
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Referer: http://localhost/sign-in-with-x/
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3
```

## Step 3: Converting the request token to an access token

To render the request token into a usable access token, your application must make a request to the [POST oauth / access\_token](/fundamentals/authentication/api-reference) endpoint, containing the `oauth_verifier` value obtained in step 2. The request token is also passed in the `oauth_token` portion of the header, but this will have been added by the signing process.

### Example request (Authorization header wrapped):

```
POST /oauth/access_token HTTP/1.1
User-Agent: themattharris' HTTP Client
Host: api.x.com
Accept: */*
Authorization: OAuth oauth_consumer_key="cChZNFj6T5R0TigYB9yd1w",
                     oauth_nonce="a9900fe68e2573b27a37f10fbad6a755",
                     oauth_signature="39cipBtIOHEEnybAR4sATQTpl2I%3D",
                     oauth_signature_method="HMAC-SHA1",
                     oauth_timestamp="1318467427",
                     oauth_token="NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0",
                     oauth_version="1.0"
Content-Length: 57
Content-Type: application/x-www-form-urlencoded

oauth_verifier=uw7NjWHT6OJ1MpJOXsHfNxoAhPKpgI8BlYDhxEjIBY
```

A successful response contains the `oauth_token`, `oauth_token_secret` parameters. The token and token secret should be stored and used for future authenticated requests to the X API. To determine the identity of the user, use [GET account / verify\_credentials](/fundamentals/authentication/api-reference).

### Example response (response body has been wrapped):

```
HTTP/1.1 200 OK
Date: Thu, 13 Oct 2011 00:57:08 GMT
Status: 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 157
Pragma: no-cache
Expires: Tue, 31 Mar 1981 05:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0
Vary: Accept-Encoding
Server: tfe

oauth_token=7588892-kagSNqWge8gB1WwE3plnFsJHAZVfxWD7Vb57p0b4&
oauth_token_secret=PbKfYqSryyeKDWz4ebtY3o5ogNLG11WJuZBc9fQrQo
```


# Sign in with X
Source: https://docs.x.com/x-for-websites/log-in-with-x/overview

Add a Sign in with X button to let users register and authenticate via OAuth on websites and mobile or desktop apps with one-click access to X APIs.

Place a button on your site or application which allows X users to enjoy the benefits of a registered user account in as little as one click. Works on websites, iOS, mobile and desktop applications.

## Features

* **Ease of use** - A new visitor to your site only has to click two buttons in order to sign in for the first time.
* **X integration** - The Sign in with X flow can grant authorization to use X APIs on your users behalf.
* **OAuth based** - A wealth of client libraries and example code are compatible with the Sign in with X API.

## Available for

* **Browsers** If your users can access a browser, you can integrate with Sign in with X. Learn about the browser sign in flow.
* **Mobile devices** Any web-connected mobile device can take advantage of Sign in with X. Learn about the mobile sign in flow.


# oEmbed API
Source: https://docs.x.com/x-for-websites/oembed-api

You can use the oEmbed API to programmatically return embedded content, such as Tweets and timelines. The response from the oEmbed API will return an HTML.

You can use the oEmbed API to programmatically return embedded content, such as [Tweets](https://developer.x.com/en/docs/twitter-for-websites/embedded-tweets/overview) and [timelines](https://developer.x.com/en/docs/twitter-for-websites/timelines/overview). 

The response from the oEmbed API will return an HTML snippet that will be automatically recognized when [X's widget JavaScript is included on the page](https://developer.x.com/web/javascript/loading).

Please note that the API is recommended for performing tasks in bulk, and we advise using our robust [publish.x.com](https://publish.x.com/#) tool for embedding content.

<Tabs>
  <Tab title="Embedded timelines">
    The returned HTML snippet will be automatically recognized as an [embedded timeline](https://developer.x.com/en/docs/twitter-for-websites/timelines/overview) when [X's widget JavaScript is included on the page](https://developer.x.com/web/javascript/loading).

    The oEmbed endpoint allows customization of the final appearance of an embedded timeline by setting the corresponding properties in HTML markup to be interpreted by X's JavaScript bundled with the HTML response by default. The format of the returned markup may change over time as X adds new features or adjusts its timeline representation.

    For a X timeline specified by the timeline URL, in an [oEmbed](https://oembed.com/)-compatible JSON format. User and list timelines are supported. The timeline markup is meant to be cached on your servers for up to the suggested cache lifetime specified by the cache\_age property.

    ## Resource URL

    *[https://publish.x.com/oembed](https://publish.x.com/oembed)*

    ## Resource Information

    |                          |      |
    | :----------------------- | :--- |
    | Response formats         | JSON |
    | Requires authentication? | No   |
    | Rate limited             | No   |

    ## Parameters

    | Name         | Description                                                                                                                                                                                                                                                                                                                                                                           | Example                                                                                                                                                          |
    | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **url**      | The URL of the X timeline to be embedded                                                                                                                                                                                                                                                                                                                                              | \*   [https://x.com/TwitterDev](https://x.com/TwitterDev)<br /> \*[https://x.com/TwitterDev/lists/national-parks](https://x.com/TwitterDev/lists/national-parks) |
    | limit        | Display up to N items where N is a value between 1 and 20 inclusive                                                                                                                                                                                                                                                                                                                   | 6                                                                                                                                                                |
    | maxwidth     | Set the maximum width of the widget. Must be between 180 and 1200 inclusive                                                                                                                                                                                                                                                                                                           | 300                                                                                                                                                              |
    | maxheight    | Set the maximum height of the widget. Must be greater than 200                                                                                                                                                                                                                                                                                                                        | 400                                                                                                                                                              |
    | omit\_script | Do not include a script element in the response                                                                                                                                                                                                                                                                                                                                       | 1                                                                                                                                                                |
    | lang         | A supported X [language code](/x-for-websites/supported-languages "X language code")                                                                                                                                                                                                                                                                                                  | es                                                                                                                                                               |
    | theme        | When set to dark, the timeline is displayed with light text over a dark background                                                                                                                                                                                                                                                                                                    | dark                                                                                                                                                             |
    | chrome       | Remove a timeline display component with space-separated tokens<br /><br />\*   noheader - hides the header<br />\*   nofooter - hides the footer, if visible<br />\*   noborders - removes all borders: around the widget, between Tweets, and inside a Tweet<br />\*   noscrollbar- crop and hide the timeline scrollbar, if visible<br />\*   transparent- remove background color | noheader%20nofooter                                                                                                                                              |
    | aria\_polite | Set an assertive [ARIA live region politeness](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live) value for Tweets added to a timeline                                                                                                                                                                                                                                   | assertive                                                                                                                                                        |
    | dnt          | When set to true, the timeline and its embedded page on your site are not used for purposes that include [personalized suggestions](https://support.x.com/articles/20169421) and [personalized ads](https://support.x.com/articles/20170405)                                                                                                                                          | true                                                                                                                                                             |

    ## Example Requests

    ```bash theme={null}
    curl --request GET --url 'https://publish.x.com/oembed?url=https%3A%2F%2Ftwitter.com%2FInterior%2Fstatus%2F507185938620219395'
    twurl -H publish.x.com "/oembed?url=https://x.com/Interior/status/463440424141459456"
    ```

    ## Example Response

    ```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}

    {
      "url": "https://x.com/TwitterDev",
      "title": "",
      "html": "<a class=\"twitter-timeline\" href=\"https://x.com/TwitterDev\">Tweets by TwitterDev</a>\n<script async src=\"//platform.x.com/widgets.js\" charset=\"utf-8\"></script>",
      "width": null,
      "height": null,
      "type": "rich",
      "cache_age": "3153600000",
      "provider_name": "Twitter",
      "provider_url": "https://x.com",
      "version": "1.0"
    }
    ```
  </Tab>

  <Tab title="Embedded Tweets">
    The returned HTML snippet will be automatically recognized as an [embedded Tweet](https://developer.x.com/web/embedded-tweets) when [X's widget JavaScript is included on the page](https://developer.x.com/web/javascript/loading). 

    The oEmbed endpoint allows customization of the final appearance of an Embedded Tweet by setting the corresponding properties in HTML markup to be interpreted by X's JavaScript bundled with the HTML response by default. The format of the returned markup may change over time as X adds new features or adjusts its Tweet representation.

    The Tweet fallback markup is meant to be cached on your servers for up to the suggested cache lifetime specified by the `cache_age` property.

    ## Resource URL

    *[https://publish.x.com/oembed](https://publish.x.com/oembed)*

    ## Resource Information

    |                          |      |
    | :----------------------- | :--- |
    | Response formats         | JSON |
    | Requires authentication? | No   |
    | Rate limited             | No   |

    ## Parameters

    | Name                                                                                                                                   | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
    | :------------------------------------------------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `url`required  <br />String                                                                                                            |         | The URL of the Tweet to be embedded                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
    | `maxwidth`  <br />Int `[220..550]`                                                                                                     | `325`   | The maximum width of a rendered Tweet in whole pixels. A supplied value under or over the allowed range will be returned as the minimum or maximum supported width respectively; the reset width value will be reflected in the returned `width` property. Note that X does not support the oEmbed `maxheight` parameter. Tweets are fundamentally text, and are therefore of unpredictable height that cannot be scaled like an image or video. Relatedly, the oEmbed response will not provide a value for `height`. Implementations that need consistent heights for Tweets should refer to the `hide_thread` and `hide_media` parameters below. |
    | `hide_media`  <br />Boolean, String or Int                                                                                             | `false` | When set to `true`, `"t"`, or `1` links in a Tweet are not expanded to photo, video, or link previews.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
    | `hide_thread`  <br />Boolean, String or Int                                                                                            | `false` | When set to `true`, `"t"`, or `1` a collapsed version of the previous Tweet in a conversation thread will not be displayed when the requested Tweet is in reply to another Tweet.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
    | `omit_script`  <br />Boolean, String or Int                                                                                            | `false` | When set to `true`, `"t"`, or `1` the `<script>` responsible for loading `widgets.js` will not be returned. Your webpages should include their own reference to `widgets.js` for use across all X widgets including [Embedded Tweets](https://developer.x.com/web/embedded-tweets).                                                                                                                                                                                                                                                                                                                                                                 |
    | `align`  <br />Enum `{left,right,center,none}`                                                                                         | `none`  | Specifies whether the embedded Tweet should be floated left, right, or center in the page relative to the parent element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
    | `lang`  <br />Enum([Language](https://developer.x.com/en/docs/twitter-for-websites/twitter-for-websites-supported-languages/overview)) | `en`    | Request returned HTML and a rendered Tweet in the specified [X language supported by embedded Tweets](https://developer.x.com/web/overview/languages).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
    | `theme`  <br />Enum `{light, dark}`                                                                                                    | `light` | When set to `dark`, the Tweet is displayed with light text over a dark background.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
    | `dnt`  <br />Boolean                                                                                                                   | `false` | When set to `true`, the Tweet and its embedded page on your site are not used for purposes that include [personalized suggestions](https://support.x.com/articles/20169421) and [personalized ads](https://support.x.com/articles/20170405).                                                                                                                                                                                                                                                                                                                                                                                                        |

    ## Example Requests

    ```bash theme={null}
    curl --request GET --url 'https://publish.x.com/oembed?url=https%3A%2F%2Ftwitter.com%2Ftwiterdev'
    twurl -H publish.x.com "/oembed?url=https://x.com/TwitterDev"
    ```

    ## Example Response

    ```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "url": "https:\/\/twitter.com\/Interior\/status\/463440424141459456",
      "author_name": "US Department of the Interior",
      "author_url": "https:\/\/twitter.com\/Interior",
      "html": "<blockquote class=\"twitter-tweet\"><p lang=\"en\" dir=\"ltr\">Sunsets don&#39;t get much better than this one over <a href=\"https:\/\/twitter.com\/GrandTetonNPS?ref_src=twsrc%5Etfw\">@GrandTetonNPS<\/a>. <a href=\"https:\/\/twitter.com\/hashtag\/nature?src=hash&amp;ref_src=twsrc%5Etfw\">#nature<\/a> <a href=\"https:\/\/twitter.com\/hashtag\/sunset?src=hash&amp;ref_src=twsrc%5Etfw\">#sunset<\/a> <a href=\"http:\/\/t.co\/YuKy2rcjyU\">pic.x.com\/YuKy2rcjyU<\/a><\/p>&mdash; US Department of the Interior (@Interior) <a href=\"https:\/\/twitter.com\/Interior\/status\/463440424141459456?ref_src=twsrc%5Etfw\">May 5, 2014<\/a><\/blockquote>\n<script async src=\"https:\/\/platform.x.com\/widgets.js\" charset=\"utf-8\"><\/script>\n",
      "width": 550,
      "height": null,
      "type": "rich",
      "cache_age": "3153600000",
      "provider_name": "Twitter",
      "provider_url": "https:\/\/twitter.com",
      "version": "1.0"
    }
    ```
  </Tab>
</Tabs>


# X for Websites
Source: https://docs.x.com/x-for-websites/overview

Overview of X for Websites tools including embedded Posts, timelines, the Post button, Follow button, oEmbed API, and the publish.x.com configurator.

<Info>
  **NOTE:** By using X for Websites you agree to the [X Developer Agreement and Policy](https://developer.x.com/en/developer-terms/agreement-and-policy).
</Info>

<CardGroup>
  <Card title="Embedded Tweets" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219">
    An [embedded Tweet](https://developer.x.com/en/docs/twitter-for-websites/embedded-tweets/overview "Embedded Tweet") brings your pick of content from X into your website articles. It’s easy to embed a Tweet by copy and pasting HTML markup from the Tweet menus on X.com and TweetDeck, programmatically in your CMS using our [oEmbed API endpoint](https://developer.x.com/en/docs/twitter-for-websites/oembed-api), or by installing our [WordPress plugin](https://wordpress.org/plugins/twitter/).

    [Learn more](https://developer.x.com/en/docs/twitter-for-websites/embedded-tweets/overview.html) <Icon icon="angle-right" />
  </Card>

  <Card>
    <iframe />
  </Card>
</CardGroup>

***

<CardGroup>
  <Card title="Embedded timelines" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219">
    [Embedded timelines](https://developer.x.com/en/docs/twitter-for-websites/timelines/overview "Embedded timelines") are an easy way to embed multiple Tweets on your website in a compact, linear view. Choose between a profile timeline to get the latest Tweets from a X account, or a List timeline containing a curated list of X accounts.

    [Learn more](https://developer.x.com/en/docs/twitter-for-websites/timelines.html) <Icon icon="angle-right" />
  </Card>

  <Card>
    [Tweets by TwitterDev](https://x.com/TwitterDev?ref_src=twsrc%5Etfw)
  </Card>
</CardGroup>

***

<CardGroup>
  <Card title="Tweet Button" icon="toggle-on">
    The [Tweet Button](https://developer.x.com/en/docs/twitter-for-websites/tweet-button/overview "Tweet button") is a social button for your website for visitors to easily share your content with their followers on X.

    [Learn more](https://developer.x.com/en/docs/twitter-for-websites/tweet-button/overview.html) <Icon icon="angle-right" />
  </Card>

  <Card title="Follow Button" icon="toggle-on">
    The [Follow Button](https://developer.x.com/en/docs/twitter-for-websites/follow-button/overview "Follow Button") is a social button enabling visitors to easily engage with your X account.

    [Learn more](https://developer.x.com/en/docs/twitter-for-websites/follow-button/overview.html)<Icon icon="angle-right" />
  </Card>
</CardGroup>

***

## Configure your own embed

Build your own embedded Tweet, timeline, or button on [X Publish](https://publish.x.com/#).

[Try it out](https://publish.x.com/#)

## Explore the oEmbed API

Use the oEmbed API to programmatically return embedded Tweets and timelines in a simple embed HTML format.

[Learn more](https://developer.x.com/en/docs/twitter-for-websites/oembed-api.html)

## Questions?

Join the discussion on our X Community developer forum. You can ask questions and help others.

[Developer forum](https://devcommunity.x.com/c/publisher/websites/9)


# Frequently asked questions
Source: https://docs.x.com/x-for-websites/post-button/faq

Frequently asked questions about the X Post button covering supported languages, dimensions, using multiple buttons on a page, HTTPS, and related accounts.

If you have another question which isn’t answered let us know on the Developer Forums.

## Does the Post Button support other languages?

Yes. Include a `lang` parameter to explicitly set the language of the Post button. View the [X for Websites supported languages](/x-for-websites/supported-languages) list to learn more about supported languages.

## What are the dimensions of the Post Button?

The Post button is 55 pixels wide and 20 pixels high.

### Internationalized Post Button

Internationalized Post buttons have slightly different dimensions.

| Language | lang code | Dimensions   |
| -------- | --------- | ------------ |
| English  | `en`      | 55px by 20px |
| Japanese | `ja`      | 80px by 20px |
| Spanish  | `es`      | 64px by 20px |

## I want to use multiple Post Buttons on my page. Is there anything I should know?

If you want to use more than one Post Button on a page you there are a couple of things you will want to check.

1. If you are using the JavaScript Post Button, make sure you only include the `widgets.js` JavaScript once. The best place to put the JavaScript is before the closing `</body>`
2. To avoid duplication of content on your page consider using the `rel="me"` and `rel="canonical"` tags in place of the via and url data points on each Post Button.

## Can I control the order of the recommended accounts?

Only two accounts are displayed and by default the via user is shown first with the first related account shown afterwards. If the user is a follower of the via user the Share Box will instead show the first two related accounts the user isn’t a follower of. No accounts are displayed if the user follows all of the suggested accounts (via and related).

Learn more about [related accounts](/x-for-websites/post-button/overview).

## Does the Post Button work over HTTPS?

Yes, the Post Button works over HTTPS.


# Hashtag Button
Source: https://docs.x.com/x-for-websites/post-button/guides/hashtag-button

A Hashtag button is a special type of Post button to encourage participation in a conversation grouped by keyword. Read more about hashtags on X.

A Hashtag button is a special type of [Post button](/x-for-websites/post-button/overview) to encourage participation in a conversation grouped by keyword. [Read more about hashtags on X](https://support.x.com/articles/49309).

## How to add a Hashtag Button to your website

1. Create a new anchor element with a `twitter-hashtag-button` class to allow the X for Websites JavaScript to discover the element and enhance the link into a Hashtag button. Set a `href` attribute value of `https://x.com/intent/tweet` to create a link to the X web intent composer.

```html theme={null}
<a class="twitter-hashtag-button"
  href="https://x.com/intent/tweet">
Post</a>
```

2. Add your hashtag of interest as a `button_hashtag` query parameter value and a component of the anchor element’s inner text.

```html theme={null}
<a class="twitter-hashtag-button"
  href="https://x.com/intent/tweet?button_hashtag=XStories">
Post #XStories</a>
```

3. Asynchronously [load the X for Websites JavaScript using our loading snippet](/x-for-websites/javascript-api/guides/set-up-x-for-websites). The JavaScript snippet will check for an existing version on the page, initialize a function queue to be executed once the widgets JavaScript has loaded, and load the widgets JavaScript asynchronously from X's CDN.

## Define secondary hashtags

Include additional hashtags in pre-populated Post text using the [hashtags web intent query parameter](/x-for-websites/post-button/guides/web-intent). A hashtag defined in the `button_hashtag` parameter and displayed in the button will appear before hashtags defined in the `hashtags` parameter.

## JavaScript factory function

X's widget JavaScript library supports dynamic insertion of a hashtag button using the `twttr.widgets.createHashtagButton` function. Pass a hashtag, target container element, and the same options supported by the [Post button JavaScript factory function](/x-for-websites/post-button/guides/javascript-factory-function).

```javascript theme={null}
twttr.widgets.createHashtagButton(
  "XStories",
  document.getElementById("container"),
  {
    size:"large"
  }
);
```


# Post Button JavaScript Factory Function
Source: https://docs.x.com/x-for-websites/post-button/guides/javascript-factory-function

Dynamically insert a Post button with twttr.widgets.createShareButton by passing a share URL, target element, and options like pre-populated share text.

The X for Websites JavaScript library supports dynamic insertion of a Post button using the `twttr.widgets.createShareButton` function. Pass a share URL, target parent element, and any custom options.

The code snippets on this page assume `widgets.js` has successfully loaded on your page. Include an asynchronous script loader on your page while initializing `window.twttr` as described in our [JavaScript loader documentation](/x-for-websites/javascript-api/guides/set-up-x-for-websites). All JavaScript code depending on `widgets.js` should execute on or after `twttr.ready`.

## Arguments

| Parameter  | Description                                                                                                                                | Example value                          |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
| `url`      | A share URL, or an empty string if you would not like to include a Post composer URL component                                             | `https://dev.x.com/`                   |
| `targetEl` | DOM node of the desired parent element                                                                                                     | `document.getElementById('container')` |
| `options`  | Override default widget options. See [Post button parameter reference](/x-for-websites/post-button/guides/parameter-reference) for details | `{ text: 'Hello world' }`              |

## Example

An element with a DOM ID of `container` exists on the page.

```html theme={null}
<div id="container"></div>
```

The code snippet below will create a new Post button with pre-selected share text of “Hello world” and a shared URL of “/” inserted into a page inside an element with a unique ID of `container`.

```javascript theme={null}
twttr.widgets.createShareButton(
  '/',
  document.getElementById('container'),
  {
    text: 'Hello World'
  }
);
```

## Promises

The `twttr.widgets.createShareButton` function returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). You can execute code after a widget has been inserted onto your page by passing a callback to the resulting promise’s `then` function.

```javascript theme={null}
twttr.widgets.createShareButton(...)
.then( function( el ) {
  console.log('Post button added.');
});
```

## Hashtag, mention buttons

Create a hashtag or mention button using the [twttr.widgets.createHashtagButton](/x-for-websites/post-button/guides/hashtag-button) and [twttr.widgets.createMentionButton](/x-for-websites/post-button/guides/mention-button) functions respectively. The same object applies.


# Mention Button
Source: https://docs.x.com/x-for-websites/post-button/guides/mention-button

A Mention button is a special type of Post button to encourage a new Post focused on an interaction between the user and a mentioned account.

A Mention button is a special type of [Post button](/x-for-websites/post-button/overview) to encourage a new Post focused on an interaction between the user and a mentioned account. A Post beginning with `@username` do not appear on the author’s timeline in the default view; the Post will only appear in the home timeline of the author’s followers if the viewer follows both the author and the mentioned user. [Read more about @replies and @mentions](https://support.x.com/articles/14023).

## How to add a Mention Button to your website

1. Create a new anchor element with a `twitter-mention-button` class to allow the X for Websites JavaScript to discover the element and enhance the link into a Mention button. Set a `href` attribute value of `https://x.com/intent/tweet` to create a link to the X web intent composer.

```html theme={null}
<a class="twitter-mention-button"
  href="https://x.com/intent/tweet">
Post</a>
```

2. Add the username of the mentioned account as a `screen_name` query parameter value and a component of the anchor element’s inner text.

```html theme={null}
<a class="twitter-mention-button"
  href="https://x.com/intent/tweet?screen_name=XDevelopers">
Post to @XDevelopers</a>
```

3. Asynchronously [load X for Websites using our loading snippet](/x-for-websites/javascript-api/guides/set-up-x-for-websites). The JavaScript snippet will check for an existing version on the page, initialize a function queue to be executed once the widgets JavaScript has loaded, and load the widgets JavaScript asynchronously from X's CDN.

## JavaScript factory function

X's widget JavaScript library supports dynamic insertion of a Mention button using the `twttr.widgets.createMentionButton` function. Pass a username, target container element, and the same options supported by the [Post button JavaScript factory function](/x-for-websites/post-button/guides/javascript-factory-function).

```html theme={null}
twttr.widgets.createMentionButton(
  "XDevelopers",
  document.getElementById("container"),
  {
    size:"large"
  }
);
```


# Post Button Parameter Reference
Source: https://docs.x.com/x-for-websites/post-button/guides/parameter-reference

Reference for Post button parameters including text, url, hashtags, via, related accounts, size, language, and DNT for HTML data-* attributes or JavaScript.

A Post button supports pre-populating share text, hashtags, and a X account reference. Associate related X accounts to drive followers.

## Post content parameters

| Parameter  | Description                                                                  | Example                             |
| ---------- | ---------------------------------------------------------------------------- | ----------------------------------- |
| `text`     | Pre-populated text highlighted in the Post composer.                         | `custom share text`                 |
| `url`      | URL included with the Post.                                                  | `https://dev.x.com/web/post-button` |
| `hashtags` | A comma-separated list of hashtags to be appended to default Post text.      | `example,demo`                      |
| `via`      | Attribute the source of a Post to a X username.                              | `xdevelopers`                       |
| `related`  | A comma-separated list of accounts related to the content of the shared URI. | `xapi,x`                            |

## Button display parameters

Customize your displayed Post Button size, button alignment, and more.

These visual parameters do not apply to Web Intents, which are styled separately by implementing sites.

| Parameter | Description                                                                                                                                                                                                                                   | Example |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `size`    | When set to `large`, display a larger version of the button. Set to `l` for iframe.                                                                                                                                                           | `large` |
| `lang`    | A supported [X language code](/x-for-websites/supported-languages).                                                                                                                                                                           | `es`    |
| `dnt`     | When set to `true`, the button and its embedded page on your site are not used for purposes that include [personalized suggestions](https://support.x.com/articles/20169421) and [personalized ads](https://support.x.com/articles/20170405). | `true`  |

### HTML `data-*` example

```html theme={null}
<a class="twitter-share-button"
  href="https://x.com/intent/tweet"
  data-size="large"
  data-text="custom share text"
  data-url="https://dev.x.com/web/tweet-button"
  data-hashtags="example,demo"
  data-via="xdevelopers"
  data-related="xapi,x">
Post
</a>
```

### JavaScript factory example

```javascript theme={null}
twttr.widgets.createShareButton(
  "https:\/\/dev.x.com\/web\/tweet-button",
  document.getElementById("tweet-container"),
  {
    size: "large",
    text: "custom share text",
    hashtags: "example,demo",
    via: "xdevelopers",
    related: "xapi,x"
  }
);
```


# Web intent
Source: https://docs.x.com/x-for-websites/post-button/guides/web-intent

Use the X Post Web Intent to let visitors compose a Post from a link, prefilled with text, hashtags, a URL, and related X account references for your page.

A Post Web Intent makes it easy for your site visitors to compose and post a Post to their audience from a link on your webpage. Sites may configure Post text and hashtags, pass a URL, and identify X accounts related to the page.

## Web Intent URL

```
https://x.com/intent/tweet
```

## Query parameters

| Parameter     | Description                                                                                                                                                                                                                                                                                                                                                                                                                          | Example Value                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| `text`        | Pre-populated UTF-8 and URL-encoded Post text. The passed text will appear pre-selected for a X user to delete or edit before posting. The length of your passed Post text should not exceed 280 characters when combined with any passed hashtags, via, or url parameters. Passed Post text which causes the Post to exceed 280 characters in length will require additional editing by a X user before they can successfully post. | `Hello%20World`                      |
| `url`         | A fully-qualified URL with an HTTP or HTTPS scheme, [URL-encoded](http://en.wikipedia.org/wiki/Percent-encoding). The provided URL will be shortened by X's t.co to the number of characters specified by short\_url\_length.                                                                                                                                                                                                        | `https%3A%2F%2Fexample.com%2F`       |
| `hashtags`    | Allow easy discovery of Posts by topic by including a comma-separated list of hashtag values without the preceding # character.                                                                                                                                                                                                                                                                                                      | `nature,sunset`                      |
| `via`         | A X username to associate with the Post, such as your site’s X account. The provided username will be appended to the end of the Post with the text “via @username”. A logged-out X user will be encouraged to sign-in or join X to engage with the via account’s Posts. The account may be suggested as an account to follow after the user posts a Post.                                                                           | `xdevelopers`                        |
| `related`     | Suggest additional X usernames related to the Post as comma-separated values. X may suggest these accounts to follow after the user posts their Post. You may provide a brief description of how the account relates to the Post with a URL-encoded comma and text after the username.                                                                                                                                               | `x%3AX%20News,xapi%3AX%20API%20News` |
| `in_reply_to` | The Post ID of a parent Post in a conversation, such as the initial Post from your site or author account.                                                                                                                                                                                                                                                                                                                           | `525001166233403393`                 |


# Post button
Source: https://docs.x.com/x-for-websites/post-button/overview

Add a Post button to your website with HTML markup and widgets.js to let visitors share content on X with pre-populated text, hashtags, and via attribution.

The Post button is a small button displayed on your website to help viewers easily share your content on X. A Post button consists of two parts: a [link to the Post composer on x.com](/x-for-websites/post-button/guides/web-intent) and X for Websites JavaScript to enhance the link with the easily recognizable Post button.

The [publish.x.com](https://publish.x.com) website provides a simple, form-based approach to generate HTML markup for a Post button you may copy-and-paste into your website template.

A [post event](/x-for-websites/javascript-api/guides/javascript-api) is triggered on your webpage when the Post button is tapped or clicked.

## How to add a Post button to your website

1. Create a new anchor element with a `twitter-share-button` class to allow the X for Websites JavaScript to discover the element and enhance the link into a Post button. Set a `href` attribute value of `https://x.com/intent/tweet` to create a link to the X web intent composer.

```html theme={null}
<a class="twitter-share-button"
  href="https://x.com/intent/tweet">
Post</a>
```

2. Pre-populate Post text and suggest related accounts by customizing [Post web intent](/x-for-websites/post-button/guides/web-intent) query parameters.

```html theme={null}
<a class="twitter-share-button"
  href="https://x.com/intent/tweet?text=Hello%20world">
Post</a>
```

3. Customize [Post button parameters](/x-for-websites/post-button/guides/parameter-reference) using `data-*` attributes.

```html theme={null}
<a class="twitter-share-button"
  href="https://x.com/intent/tweet?text=Hello%20world"
  data-size="large">
Post</a>
```

4. Asynchronously [load the X for Websites JavaScript using our loading snippet](/x-for-websites/javascript-api/guides/set-up-x-for-websites). The JavaScript snippet will check for an existing version already on the page, initialize a function queue to be executed once the widgets JavaScript has loaded, and load the widgets JavaScript asynchronously from X’s CDN.

## Post text components

### text

A `text` parameter appears pre-selected in a Post composer. The Post author may easily remove the text with a single delete action.

The `text` parameter may be auto-populated from the webpage’s `<title>` element if not explicitly set.

### url

The `url` parameter contains an absolute HTTP or HTTPS URL to be shared on X. The shared URL will be [automatically shortened](https://support.x.com/articles/78124-how-to-post-shortened-links-urls) in a published Post. A [Card](https://dev.x.com/cards/overview) may appear for a shared URL.

The `url` parameter may be auto-populated from a [canonical link element](http://en.wikipedia.org/wiki/Canonical_link_element) (`<link rel="canonical">`) or the [location.href](https://html.spec.whatwg.org/multipage/browsers.html#the-location-interface) of the page when not explicitly set.

```html theme={null}
<link rel="canonical"
  href="/web/tweet-button">
```

### hashtags

Add a comma-separated list of `hashtags` to a Post using the `hashtags` parameter. Omit a preceding “#” from each hashtag; the Post composer will automatically add the proper space-separated hashtag by language.

### via

Attribute the source of a Post to a X username using the `via` parameter. The attribution will appear in a Post as ” `via @username`” translated into the language of the Post author.

A `via` parameter may be auto-populated from a link or anchor element linked to a X profile page with a `me` relationship token.

```html theme={null}
<link rel="me"
  href="https://x.com/XDevelopers"
>
```

## Button customization

### Size

Add a `data-size` attribute value of `large` to display a larger Post button.


# Privacy
Source: https://docs.x.com/x-for-websites/privacy

Privacy information for X for Websites widgets, including what data X collects from embeds, how it is used, and how to control tracking on your site.

## What information does X collect through X for Websites and how is that information used?

When you view X content such as embedded Tweets, buttons, or timelines integrated into other websites using X for Websites, X may receive information, including the web page you visited, your IP address, browser type, operating system, and cookie information. This information helps us to improve our products and services. Learn more about the information we receive and how we use it in our [privacy policy](https://x.com/privacy) and [cookies policy](https://help.x.com/en/rules-and-policies/x-cookies).

## How long do you keep this information?

To protect privacy, we never associate this web browsing history we collect from X for Websites with customers’ names, email addresses, phone numbers, or X handles, and we delete, obfuscate, or aggregate it after no longer than 30 days, as explained in our [privacy policy](https://x.com/privacy). We don't store this web browsing history from certain domains such as .mil and .gov.


# Supported languages and browsers
Source: https://docs.x.com/x-for-websites/supported-languages

Languages and browsers supported by X for Websites widgets, including locale codes, language fallbacks, and minimum supported browser versions.

## Language Support

Translated widget text is available in 34 of the [languages supported by x.com](https://about.x.com/en).

Languages supported by X for Websites widgets and buttons:

| Name                  | Language code |
| :-------------------- | :------------ |
| English (default)     | `en`          |
| Arabic                | `ar`          |
| Bengali               | `bn`          |
| Czech                 | `cs`          |
| Danish                | `da`          |
| German                | `de`          |
| Greek                 | `el`          |
| Spanish               | `es`          |
| Persian               | `fa`          |
| Finnish               | `fi`          |
| Filipino              | `fil`         |
| French                | `fr`          |
| Hebrew                | `he`          |
| Hindi                 | `hi`          |
| Hungarian             | `hu`          |
| Indonesian            | `id`          |
| Italian               | `it`          |
| Japanese              | `ja`          |
| Korean                | `ko`          |
| Malay                 | `msa`         |
| Dutch                 | `nl`          |
| Norwegian             | `no`          |
| Polish                | `pl`          |
| Portuguese            | `pt`          |
| Romanian              | `ro`          |
| Russian               | `ru`          |
| Swedish               | `sv`          |
| Thai                  | `th`          |
| Turkish               | `tr`          |
| Ukrainian             | `uk`          |
| Urdu                  | `ur`          |
| Vietnamese            | `vi`          |
| Chinese (Simplified)  | `zh-cn`       |
| Chinese (Traditional) | `zh-tw`       |

```html theme={null}
<a
  class="twitter-share-button"
  href="https://x.com/share"
  data-lang="es">
X
</a>
```

X for Websites will extract the most appropriate language from its position in the DOM tree, if no language is provided in the widget markup. Pages which define an unsupported script or region will be mapped to the closest available language: e.g. `pt-BR` will use `pt` if Portuguese is available but a Brazilian regional localization is not.

United States English is the default if a page’s language code does not match any available translation.

<Note>
  Setting the language only affects the language of X elements such as action text and timestamp display; Tweet text is always displayed in its originally authored language.
</Note>

## Browser support

We support all browsers and webviews that support [ECMAScript Level 5](https://en.wikipedia.org/wiki/ECMAScript#5th_Edition) and above – this should include all modern browsers and webviews. We build and test our widgets on all modern desktop, and mobile browsers, as well as mobile webviews.

The only exceptions where we do not render are browsers that do not support ECMAScript level 5, and Internet Explorer 11 and below.


# Embedded lists
Source: https://docs.x.com/x-for-websites/timelines/guides/list-timeline

Embed a X list timeline showing the latest Posts from a curated public list using an anchor tag with the list URL or the twttr.widgets.createTimeline factory.

A list timeline displays the latest Posts ordered from newest to oldest from a curated public list of X accounts. The timeline includes a header displaying the list’s name, description, and curator. [Read more about X lists](https://support.x.com/articles/76460).

## HTML markup

A responsive timeline backed by a X list can be added to a webpage through a common HTML template.

A template example:

```html theme={null}
<a class="twitter-timeline"
  href="https://x.com/{screen_name}/lists/{slug}">
Posts from https://x.com/{screen_name}/lists/{slug}
</a>
```

```html theme={null}
<a class="twitter-timeline"
  href="https://x.com/x/lists/official-twitter-accts">
Posts from https://x.com/x/lists/official-twitter-accts
</a>
```

## JavaScript factory function

The X for Websites JavaScript library supports dynamic insertion of an embedded list timeline using the `twttr.widgets.createTimeline` function. Pass a data source definition, target container element, and optional options object to insert an embedded timeline into your page.

HTML `data-*` parameters are camelCased when passed as an options object property.

```javascript theme={null}
twttr.widgets.createTimeline(
  {
    sourceType: "list",
    ownerScreenName: "XDevelopers",
    slug: "national-parks"
  },
  document.getElementById("container")
);
```


# oEmbed API
Source: https://docs.x.com/x-for-websites/timelines/guides/oembed-api

Return a simple embed HTML for a X timeline specified by the timeline URL, in an oEmbed-compatible JSON format. User, list, likes, and collection timelines.

Return a simple embed HTML for a X timeline specified by the timeline URL, in an [oEmbed](https://oembed.com/)-compatible JSON format. User, list, likes, and collection timelines are supported.

The timeline markup is meant to be cached on your servers for up to the suggested cache lifetime specified by the `cache_age` property.

## Resource URL

```
https://publish.x.com/oembed
```

## Resource Information

| Feature                  | Value |
| ------------------------ | ----- |
| Response formats         | JSON  |
| Requires authentication? | No    |
| Rate limited             | No    |

## Parameters

| Name           | Description                                                                                                                                                                                                                                                                                                                                                                 | Example                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `url`          | The URL of the X timeline to be embedded                                                                                                                                                                                                                                                                                                                                    | `https://x.com/XDevelopers`<br />`https://x.com/XDevelopers/lists/national-parks` |
| `widget_type`  | Collection timelines only. Set to `grid` to display Posts in a grid layout                                                                                                                                                                                                                                                                                                  | `grid`                                                                            |
| `limit`        | Display up to N items where N is a value between 1 and 20 inclusive                                                                                                                                                                                                                                                                                                         | `6`                                                                               |
| `maxwidth`     | Set the maximum width of the widget. Must be between 180 and 1200 inclusive                                                                                                                                                                                                                                                                                                 | `300`                                                                             |
| `maxheight`    | Set the maximum height of the widget. Must be greater than 200                                                                                                                                                                                                                                                                                                              | `400`                                                                             |
| `omit_script`  | Do not include a `<script>` element in the response                                                                                                                                                                                                                                                                                                                         | `1`                                                                               |
| `lang`         | A supported [X language code](/x-for-websites/supported-languages)                                                                                                                                                                                                                                                                                                          | `es`                                                                              |
| `related`      | Suggest additional X screen names related to the widget as comma-separated values. X may suggest these accounts to follow after the user likes a displayed Post. You may provide a brief description of how the account relates to the Post with a URL-encoded comma and text after the screen name                                                                         | `x%3AX%20News,xapi%3AX%20API%20News`                                              |
| `theme`        | When set to `dark`, the timeline is displayed with light text over a dark background                                                                                                                                                                                                                                                                                        | `dark`                                                                            |
| `border_color` | Set the color of widget component borders, including the border between Posts, with a [hexadecimal color value](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet)                                                                                                                                                                                                       | `%23a80000`                                                                       |
| `chrome`       | Remove a timeline display component with space-separated tokens:<br />• `noheader` — hides the header<br />• `nofooter` — hides the footer, if visible<br />• `noborders` — removes all borders: around the widget, between Posts, and inside a Post<br />• `noscrollbar` — crop and hide the timeline scrollbar, if visible<br />• `transparent` — remove background color | `noheader%20nofooter`                                                             |
| `aria_polite`  | Set an assertive [ARIA live region politeness](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live) value for Posts added to a timeline                                                                                                                                                                                                                          | `assertive`                                                                       |
| `dnt`          | When set to `true`, the timeline and its embedded page on your site are not used for purposes that include [personalized suggestions](https://support.x.com/articles/20169421) and [personalized ads](https://support.x.com/articles/20170405)                                                                                                                              | `true`                                                                            |

## Example requests

```
GET https://publish.x.com/oembed?url=https://x.com/XDevelopers
twurl -H publish.x.com "/oembed?url=https://x.com/XDevelopers"
```

## Example Response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "url": "https://x.com/XDevelopers",
  "title": "",
  "html": "<a class=\"twitter-timeline\" href=\"https://x.com/XDevelopers\">Posts by XDevelopers</a>\n<script async src=\"//platform.x.com/widgets.js\" charset=\"utf-8\"></script>",
  "width": null,
  "height": null,
  "type": "rich",
  "cache_age": "3153600000",
  "provider_name": "X",
  "provider_url": "https://x.com",
  "version": "1.0"
}
```


# Parameters
Source: https://docs.x.com/x-for-websites/timelines/guides/parameter-reference

Reference for embedded timeline data-* options including chrome, theme, width, height, tweet-limit, show-replies, aria-polite accessibility, and DNT settings.

Customize an embedded timeline with `data-*` attributes added to a fallback anchor element or passed to a JavaScript factory function in an options object.

| Option         | Values                                                            | Default                              | Notes                                                                                                                                                                                                                                          |
| -------------- | ----------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `show-replies` | `true`                                                            | `false`                              | Show Posts in response to another Post or account                                                                                                                                                                                              |
| `chrome`       | `noheader`, `nofooter`, `noborders`, `transparent`, `noscrollbar` | `Undefined`                          | Toggle the display of design elements in the widget. This parameter is a space-separated list of values                                                                                                                                        |
| `theme`        | `dark`                                                            | `light`                              | Display light text on a dark background                                                                                                                                                                                                        |
| `width`        | Positive integer                                                  | `auto` (derived from container size) | Set the maximum px width of the embedded Post                                                                                                                                                                                                  |
| `height`       | Positive integer                                                  | `600`                                | Set a fixed px height of the embedded widget                                                                                                                                                                                                   |
| `tweet-limit`  | Range: `1`–`20`                                                   | `Undefined`                          | Render a timeline statically, displaying only *n* number of Posts. The height parameter has no effect when a Post limit is set                                                                                                                 |
| `aria-polite`  | `polite`, `assertive`, `rude`                                     | `polite`                             | Apply the specified aria-polite behavior to the rendered timeline. New Posts may be added to the top of a timeline, affecting screen readers                                                                                                   |
| `dnt`          | `true`, `false`                                                   | `false`                              | When set to `true`, the timeline and its embedded page on your site are not used for purposes that include [personalized suggestions](https://support.x.com/articles/20169421) and [personalized ads](https://support.x.com/articles/20170405) |

## HTML example

```html theme={null}
<a class="twitter-timeline"
  href="https://x.com/XDevelopers"
  data-width="350"
  data-height="450"
  data-chrome="nofooter noheader"
  data-tweet-limit="2">
Posts by @XDevelopers
</a>
```

## JavaScript factory example

```javascript title="Example" lines wrap icon="square-js" theme={null}
twttr.widgets.createTimeline(
  {
    sourceType: "profile",
    screenName: "xdevelopers"
  },
  document.getElementById("container"),
  {
    height: 400,
    chrome: "nofooter",
    tweetLimit: 2
  }
);
```


# Embedded profiles
Source: https://docs.x.com/x-for-websites/timelines/guides/profile-timeline

Embed an X profile timeline displaying the latest Posts from a public account using anchor markup with the profile URL or twttr.widgets.createTimeline.

A profile timeline displays the latest Posts ordered from newest to oldest from a specific public X account.

## HTML markup

A responsive profile timeline can be added to a webpage through a common HTML template. Generate markup for an embedded profile timeline on [publish.x.com](https://publish.x.com).

A template example:

```html theme={null}
<a class="twitter-timeline"
  href="https://x.com/{screen_name}">
Posts by @{screen_name}
</a>
```

```html theme={null}
<a class="twitter-timeline"
  href="https://x.com/XDevelopers">
Posts by @XDevelopers
</a>
```

## JavaScript factory function

X's widget JavaScript library supports dynamic insertion of an embedded profile timeline using the `twttr.widgets.createTimeline` function. Pass a data source definition, target container element, and optional options object to insert an embedded timeline into your page.

HTML `data-*` parameters are camelCased when passed as an options object property.

```javascript theme={null}
twttr.widgets.createTimeline(
  {
    sourceType: "profile",
    screenName: "XDevelopers"
  },
  document.getElementById("container")
);
```


# Embedded Timelines
Source: https://docs.x.com/x-for-websites/timelines/overview

Embed X profile and list timelines on your website with sizing, custom chrome, theme, Post limits, and the publish.x.com markup generator for easy setup.

Embedded timelines are an easy way to embed Posts on your website in a compact, linear view. Choose between a profile timeline to get the latest Posts from a X account, or a List timeline containing a curated list of Posts from your favorite X accounts.

An embedded timeline consists of two parts: including an embed code that links your webpage to the timeline on x.com, and the X for Websites JavaScript to transform the link into a fully-rendered timeline.

<Note>
  **Please note:**

  We retired the Likes, Collections, and Moments timelines on January 13, 2023.

  We recommend you use the [Profile](/x-for-websites/timelines/guides/profile-timeline) and [Lists](/x-for-websites/timelines/guides/list-timeline) timelines, which we’re updating to become faster, easier to use, and more up-to-date with X features and functionality.

  You can learn more about this change in our [announcement](https://devcommunity.x.com/t/removing-support-for-embedded-like-collection-and-moment-timelines/150313).
</Note>

## Timeline types

### Profile timeline

A profile timeline displays the latest Posts from the specified (public) X account.

### List timeline

A list timeline displays the latest Posts from a curated, public list of X accounts. The timeline includes a header displaying the list’s name, description, and curator. To create lists on x.com or in the X app, learn more here.

## How to add an embedded timeline to your website

Visit [publish.x.com](https://publish.x.com) to generate embed codes for profiles and lists.

## Customization

### Dimensions

An embedded timeline automatically adjusts to the width of its parent element with a minimum width of 180 pixels and a maximum width of 520 pixels. The grid display has a minimum width of 220 pixels. Set the maximum width or the maximum height of an embedded timeline by adding a data-width or data-height attribute to the embed code anchor element.

```html theme={null}
<a class="twitter-timeline"
  href="https://x.com/XDevelopers"
  data-width="300"
  data-height="300">
Posts by @XDevelopers
</a>
```

### Custom chrome

Control the frame around the linear timeline by setting a `data-chrome` attribute with space-separated tokens for each chrome component.

| Token         | Description                                                                                                                                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `noheader`    | Hides the timeline header. Implementing sites must add their own X attribution, link to the source timeline, and comply with other X [display requirements](https://about.x.com/company/display-requirements). |
| `nofooter`    | Hides the timeline footer and Post composer link, if included in the timeline widget type.                                                                                                                     |
| `noborders`   | Removes all borders within the widget including borders surrounding the widget area and separating Posts.                                                                                                      |
| `noscrollbar` | Crops and hides the main timeline scrollbar, if visible. Please consider that hiding standard user interface components can affect the accessibility of your website.                                          |
| `transparent` | Removes the widget’s background color.                                                                                                                                                                         |

#### Example

```html theme={null}
<a class="twitter-timeline"
  href="https://x.com/XDevelopers"
  data-chrome="nofooter noborders">
Posts by @XDevelopers
</a>
```

### Limiting the number of Posts displayed

Display a specific number of items between 1 and 20 by customizing your embed HTML.

Add a `data-tweet-limit` attribute to the embed code to specify a number of Posts. The timeline will automatically adjust its height to display a specified number of Posts. The timeline is fixed after display; it will not poll for new Posts until the page is refreshed.

#### Example

```html theme={null}
<a class="twitter-timeline"
  href="https://x.com/XDevelopers"
  data-tweet-limit="3">
Posts by @XDevelopers
</a>
```

### Accessibility: Override ARIA live politeness

An embedded timeline describes its content for screen readers and other assistive technologies using additional markup defined in [WAI-ARIA standards](http://www.w3.org/WAI/intro/aria.php). A timeline widget is a [live region of a page](http://www.w3.org/WAI/PF/aria-practices/#liveprops) which will receive updates when new Posts become available.

By default, a timeline has a politeness value of `polite` by default; set a `data-aria-polite` attribute value of assertive to set the embedded timeline live region politeness to `assertive`, for example if you’re using the embedded Timeline as a primary source of live content in your page.

```html theme={null}
<a class="twitter-timeline"
  href="https://x.com/XDevelopers"
  data-aria-polite="assertive">
Posts by @XDevelopers
</a>
```


# Tools and libraries
Source: https://docs.x.com/x-for-websites/tools-and-libraries

Tools, libraries, and plugins for adding X for Websites embeds and widgets to your site, including WordPress, content management system integrations.

## Official resources

The tools below can get you started with X for Websites.

<CardGroup>
  <Card title="publish.x.com" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-logo-x.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=53e3153f3b8d6efdad31484ef133b274" href="https://publish.x.com/">
    Build your own embedded Tweet, timeline, or button.
  </Card>

  <Card title="Twitter for WordPress" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-logo-x.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=53e3153f3b8d6efdad31484ef133b274" href="https://github.com/twitter/wordpress">
    An official plugin to optimize your WordPress site for X, including Tweet embeds and X Cards.
  </Card>

  <Card title="twemoji" icon="https://mintcdn.com/x-preview/SxzTbJaLjs3MidH1/icons/xds/icon-logo-x.svg?fit=max&auto=format&n=SxzTbJaLjs3MidH1&q=85&s=53e3153f3b8d6efdad31484ef133b274" href="https://twemoji.x.com/">
    X’s free, open source emoji character set, including a JavaScript library for cross-platform support.
  </Card>
</CardGroup>

## Community tools and libraries

The following tools are provided and supported by the wider web developer community, and are not official resources. We thank the community for these contributions!

### Gatsby

<CardGroup>
  <Card title="gatsby-remark-embedded" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="https://github.com/MichaelDeBoey/gatsby-remark-embedder">
    by [@MichaelDeBoey](https://github.com/MichaelDeBoey)
  </Card>
</CardGroup>

### React

<CardGroup>
  <Card title="react-tweet" icon="react" href="https://github.com/mannynotfound/react-tweet">
    by [@mannynotfound](https://github.com/mannynotfound)
  </Card>

  <Card title="react-tweet-embed" icon="react" href="https://github.com/capaj/react-tweet-embed">
    by [@capaj](https://github.com/capaj)
  </Card>

  <Card title="react-twitter-widgets" icon="react" href="https://github.com/andrewsuzuki/react-twitter-widgets">
    by [@andrewsuzuki](https://github.com/andrewsuzuki)
  </Card>

  <Card title="react-twitter-embed" icon="react" href="https://github.com/saurabhnemade/react-twitter-embed">
    by [@saurabhnemade](https://github.com/saurabhnemade)
  </Card>
</CardGroup>

### Web Components

<CardGroup>
  <Card title="twitter-status" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="https://github.com/abraham/twitter-status">
    by [@abraham](https://x.com/abraham)
  </Card>

  <Card title="twitter-user" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="https://github.com/abraham/twitter-user">
    by [@abraham](https://x.com/abraham)
  </Card>
</CardGroup>

### WordPress

<CardGroup>
  <Card title="TwitterWP" icon="wordpress" href="https://github.com/jtsternberg/TwitterWP">
    by [@jsternberg](https://github.com/jtsternberg)
  </Card>
</CardGroup>


# Image Resources
Source: https://docs.x.com/x-for-websites/web-intents/image-resources

Image resources, logos, and Post action marks for building a consistent X user experience in apps and websites that integrate Web Intents and embeds.

The resources are available to support a consistent user experience in applications leveraging Twitter & sites using Web Intents. It is recommended that you store these within your own application. For more information on using these marks, consult our Display Requirements.

## X Logo

Download current X logo assets (including various sizes and colors) directly from the official [brand toolkit](https://about.x.com/en/who-we-are/brand-toolkit).

## Tweet Actions

A Tweet action represents a possible action on a Tweet with an “on” state if the viewer has already completed the action.

All Tweet actions are displayed with a medium grey (#AAB8C2) fill in their default state. All Tweet actions should set 50% opacity when the action is being activated by the viewer (e.g. `:active` CSS pseudo). The action retains the previous fill color during its pressed / activation state, switching to the “on” state after the action becomes activated.

Retweet and like actions appear in an “on” state if the current viewer has performed the action. A `retweeted` or `favorited` [Tweet object](/x-api/fundamentals/data-dictionary/reference#post-tweet) property set to true communicates the expected “on” display state.

A retweet action is turned off if the current viewer matches the author of the Tweet. A turned off action has 30% opacity.

## Reply

```xml theme={null}
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 65 72">
  <path d="M41 31h-9V19c0-1.14-.647-2.183-1.668-2.688-1.022-.507-2.243-.39-3.15.302l-21 16C5.438 33.18 5 34.064 5 35s.437 1.82 1.182 2.387l21 16c.533.405 1.174.613 1.82.613.453 0 .908-.103 1.33-.312C31.354 53.183 32 52.14 32 51V39h9c5.514 0 10 4.486 10 10 0 2.21 1.79 4 4 4s4-1.79 4-4c0-9.925-8.075-18-18-18z"/>
</svg>
```

The reply icon opacity should be adjusted during icon activation. A reply Tweet action does not have an “on” state: a new reply is always available.

### Reply Tweet action expected colors and opacity

| Default   | Pressed     |
| --------- | ----------- |
| `#AAB8C2` | 50% opacity |

## Retweet

```xml theme={null}
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 75 72">
  <path d="M70.676 36.644C70.166 35.636 69.13 35 68 35h-7V19c0-2.21-1.79-4-4-4H34c-2.21 0-4 1.79-4 4s1.79 4 4 4h18c.552 0 .998.446 1 .998V35h-7c-1.13 0-2.165.636-2.676 1.644-.51 1.01-.412 2.22.257 3.13l11 15C55.148 55.545 56.046 56 57 56s1.855-.455 2.42-1.226l11-15c.668-.912.767-2.122.256-3.13zM40 48H22c-.54 0-.97-.427-.992-.96L21 36h7c1.13 0 2.166-.636 2.677-1.644.51-1.01.412-2.22-.257-3.13l-11-15C18.854 15.455 17.956 15 17 15s-1.854.455-2.42 1.226l-11 15c-.667.912-.767 2.122-.255 3.13C3.835 35.365 4.87 36 6 36h7l.012 16.003c.002 2.208 1.792 3.997 4 3.997h22.99c2.208 0 4-1.79 4-4s-1.792-4-4-4z"/>
</svg>
```

The retweet icon opacity should be adjusted during icon activation. The retweet icon should appear in the “on” state if the Tweet object response for the current viewer has a `retweeted` property set to `true`. An inactive Tweet action state may exist when the current viewer is the same as the Tweet author.

### Retweet Tweet action expected colors and opacity

| Default   | Pressed     | Inactive    | On & Hover |
| --------- | ----------- | ----------- | ---------- |
| `#AAB8C2` | 50% opacity | 30% opacity | `#19CF86`  |

## Like

```xml theme={null}
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 54 72">
  <path d="M38.723,12c-7.187,0-11.16,7.306-11.723,8.131C26.437,19.306,22.504,12,15.277,12C8.791,12,3.533,18.163,3.533,24.647 C3.533,39.964,21.891,55.907,27,56c5.109-0.093,23.467-16.036,23.467-31.353C50.467,18.163,45.209,12,38.723,12z"/>
</svg>
```

The like icon opacity should be adjusted during icon activation. The like icon should appear in the “on” state if the Tweet object response for the current viewer has a `favorited` property set to `true`.

#### Like Tweet action expected colors and opacity

| Default   | Pressed     | On & Hover |
| --------- | ----------- | ---------- |
| `#AAB8C2` | 50% opacity | `#E81C4F`  |


# Web Intents
Source: https://docs.x.com/x-for-websites/web-intents/overview

Use X Web Intents to let visitors post, reply, retweet, like, follow accounts, or view mini-profiles directly from your site without authorizing an app.

Web Intents provide flows for working with Tweets & X Users: Tweet, Reply, Retweet, Like, and Follow. They make it possible for users to interact with X content in the context of your site, without leaving the page or having to authorize a new app just for the interaction. Web intents are mobile web friendly, include native app handlers on iOS and Android when the X app is installed, and are super easy to implement.

## Working with Web Intents

Web Intents are the simplest way to let people Tweet or follow X accounts directly from your site. Web Intents automatically bring a viewer into the best logged-in experience to complete your specified action, including Tweet composers or X profile views inside X for iOS and X for Android apps. If a viewer does not have a X account they will have the opportunity to log in to X or create an account before completing the originally-specified action. Web Intents do not require setting up a X application, storing app credentials, or prompting a viewer for app permissions before posting.

[The X for Websites JavaScript](/x-for-websites/javascript-api/guides/set-up-x-for-websites) will automatically fire appropriate [JavaScript events](/x-for-websites/javascript-api/guides/javascript-api) when included on a webpage.

Web Intents cannot be loaded inside an iframe. A X author must view the full webpage before deciding to author a new Tweet or Tweet action pre-populated by your specified Web Intent or follow a specified X account.

Images for icons for likes, replies, and reposts are all available on our [Image Resources](/x-for-websites/web-intents/image-resources) page. Consult our [Display Requirements](https://about.x.com/company/display-requirements) for tips on rendering Tweets and other X resources.

If your audience speaks a language other than English, we recommend you use localized intents.

### Get Started

Web Intents can be invoked flexibly through a light combination of JavaScript and HTML and are meant to be opened in a new window.

The easiest way to use intents is to include the X for Websites JavaScript on any web page you wish to invoke an intent. If you’ve already set up the [Tweet button](/x-for-websites/post-button/overview), you’re already prepared for Web Intents.

When combined with standard anchor tags and [familiar iconography](https://dev.x.com/basics/image-resources) like the examples below, this JavaScript will automatically open a window of the appropriate size when clicked. You only need to load `platform.x.com/widgets.js` once.

```html theme={null}
<script type="text/javascript" async src="https://platform.twitter.com/widgets.js"></script>
<a href="https://twitter.com/intent/tweet?in_reply_to=463440424141459456">Reply</a>
<a href="https://twitter.com/intent/retweet?tweet_id=463440424141459456">Retweet</a>
<a href="https://twitter.com/intent/like?tweet_id=463440424141459456">Like</a>
```

## List of Web Intents

### Tweet or Reply to a Tweet

* [https://x.com/intent/tweet](https://x.com/intent/tweet?in_reply_to=463440424141459456\&related=xdevelopers)

View the [Tweet Web Intent documentation](/x-for-websites/post-button/overview) for more information about the Tweet intent.

### Retweet a Tweet

* [https://x.com/intent/retweet](https://x.com/intent/retweet?tweet_id=463440424141459456\&related=xdevelopers,x,support)

[Retweets](https://support.x.com/articles/77606-what-is-retweet-rt) are a powerful way to enable your users to share your content with their followers.

#### Supported Parameters

* `tweet_id`

Every Tweet is identified by an ID. You can find this value from the API or by viewing the permalink page for any Tweet, usually accessible by clicking on the “published at” date of a tweet.

### Like a Tweet

* [https://twitter.com/intent/like](https://x.com/intent/like?tweet_id=463440424141459456)

Users [like](https://support.x.com/articles/20169874) for a variety of reasons: when they love a Tweet, when they want to save it for later, or to offer a signal of thanks. The like intent allows you to provide this Tweet action and follow up with relevant suggested accounts for the user to follow.

#### Supported Parameters

* `tweet_id`

Every Tweet is identified by an ID. You can find this value from the API or by viewing the permalink page for any Tweet, usually accessible by clicking on the timestamp displayed alongside a Tweet.

### Mini-Profile

* [https://x.com/intent/user](https://x.com/intent/user?screen_name=NASA)

This Intent provides an unobtrusive way to link names of people, companies, and services to their X accounts. The new tab prominently features the account’s profile picture, bio, recent tweets and an easy-to-use Follow button.

More image resources.

#### Supported parameters

* `screen_name`

Every X user has a screen name, but they are subject to change. We recommend using user\_id whenever possible.

* `user_id`

X User IDs are available from the API and uniquely identify a user.

### Follow

* [https://twitter.com/intent/follow](https://x.com/intent/follow?screen_name=NASA)

A [follow Web Intent](/x-for-websites/follow-button/guides/web-intent-follow-button) displays an inline sign in form for logged out users and follows the target X account on successful login.

## Localization

You may pass a `lang` query parameter as part of any web intent to override the language display of a logged-in user or languages accepted by a browser. See [X for Websites languages](/x-for-websites/supported-languages) for a list of supported `lang` values.

## Optimization

### Limited Dependencies

Some sites may prefer to embed the unobtrusive web intents JavaScript inline or without a dependency to `platform.twitter.com`. The snippet below will offer the equivalent functionality without the external dependency.

```javascript title="Example" expandable lines wrap icon="square-js" theme={null}
(function() {
  if (window.__twitterIntentHandler) return;
  var intentRegex = /twitter\.com\/intent\/(\w+)/,
      windowOptions = 'scrollbars=yes,resizable=yes,toolbar=no,location=yes',
      width = 550,
      height = 420,
      winHeight = screen.height,
      winWidth = screen.width;

  function handleIntent(e) {
    e = e || window.event;
    var target = e.target || e.srcElement,
        m, left, top;

    while (target && target.nodeName.toLowerCase() !== 'a') {
      target = target.parentNode;
    }

    if (target && target.nodeName.toLowerCase() === 'a' && target.href) {
      m = target.href.match(intentRegex);
      if (m) {
        left = Math.round((winWidth / 2) - (width / 2));
        top = 0;

        if (winHeight > height) {
          top = Math.round((winHeight / 2) - (height / 2));
        }

        window.open(target.href, 'intent', windowOptions + ',width=' + width +
                                           ',height=' + height + ',left=' + left + ',top=' + top);
        e.returnValue = false;
        e.preventDefault && e.preventDefault();
      }
    }
  }

  if (document.addEventListener) {
    document.addEventListener('click', handleIntent, false);
  } else if (document.attachEvent) {
    document.attachEvent('onclick', handleIntent);
  }
  window.__twitterIntentHandler = true;
}());
```


# X Widgets Webpage Properties
Source: https://docs.x.com/x-for-websites/webpage-properties

Configure X widget defaults across a site with meta and link elements, including dnt, lang, in-reply-to, and other webpage-level widget properties.

Set widget preferences across an entire website by including `<meta>` and `<link>` elements in your pages page.

Widget settings specified in a `<meta>` may be overridden at the individual widget level. Order of precedence:

1. web intent link query parameter
2. widget attribute
3. meta or link element

## Turn off DOM scan for widgets and buttons

The X for Websites JavaScript scans `document.body` after initialization to locate buttons, widgets, and web intents for enhancement. Turn off this scan if X content is only loaded via [JavaScript factory functions](/x-for-websites/javascript-api/guides/set-up-x-for-websites) or if you prefer to directly [call load](/x-for-websites/javascript-api/guides/scripting-loading-and-initialization) on a smaller fragment of the page.

```html theme={null}
<meta
  name="twitter:widgets:autoload"
  content="off">
```

## Canonical link

The [Post button](/x-for-websites/post-button/overview) uses the [canonical link relation of the page](http://tools.ietf.org/html/rfc6596) expressed in a `<link>` as the shared URL if the URL property is not set in the button markup.

Add a canonical link in the `<head>` section of your webpage.

```html theme={null}
<link
  rel="canonical"
  href="/">
```

## Identify the X profile of the page

Populate the `via` property of a Tweet button by linking to your X profile page with a me link relationship token.

Set a `me` link relationship in the `<head>` section of your webpage.

```xml theme={null}
<link
  rel="me"
  href="https://x.com/XDevelopers">
```

You may also set a `me` relationship from an anchor element on your page, such as a Follow button.

```html theme={null}
<a
  class="x-follow-button"
  rel="me"
  href="https://x.com/XDevelopers">
Follow @XDevelopers
</a>
```

## Theme

Override the default `light` theme preference for an [embedded Post](/x-for-websites/embedded-posts/overview) or an [embedded Timeline](/x-for-websites/timelines/overview).

```html theme={null}
<meta
  name="twitter:widgets:theme"
  content="dark">
```

## Do not track parameter

You may choose whether X widgets on your site help to personalize content and suggestions for X users, including ads. You can opt out of having information from your website used for personalization by following the instructions below. Include the following snippet within the `<meta>` and `<link>` elements on your pages that include X for Websites widgets:

```html theme={null}
<meta name="twitter:dnt" content="on">
```

You may also opt-out of this data use for a specific widget, and can do so by setting the optional `data-dnt` parameter to be true, as shown in the example below:

```html theme={null}
<a
  class="twitter-share-button"
  href="https://x.com/share"
  data-dnt="true">
Tweet</a>
<script async defer
  src="//platform.x.com/widgets.js"
  charset="utf-8">
</script>
```

## Turn off functionality which may trigger Content Security Policy warnings

An embedded Tweet or embedded Timeline may display with restricted capabilities when a [Content Security Policy](http://en.wikipedia.org/wiki/Content_Security_Policy) restricts inline loading of X. Set `csp=on` to turn off functionality which could display Content Security Policy warnings on your site.

```html theme={null}
<meta
  name="twitter:widgets:csp"
  content="on">
```


# Build X Chat UI apps with WASM so private keys never leave the browser
Source: https://docs.x.com/xchat/building-ui-apps-with-wasm

Run the Chat XDK in the browser with WebAssembly so encryption stays on-device, private keys never hit your server, and users only send ciphertext through the X API.

For **user-facing chat UIs**, run the [Chat XDK](/xchat/xchat-xdk) **in the browser** via its JavaScript/WASM package (`@xdevplatform/chat-xdk`). Private identity and signing keys stay on the user's device. Your servers (and X) only ever see **ciphertext**, public keys, and OAuth tokens—not the PIN or private key material used to encrypt and sign messages.

This page is the recommended architecture for client apps. For PIN and key-handling rules that apply to every app type, see [Handling private keys](/xchat/handling-private-keys).

***

## Why WASM for UI apps

| Approach                               | Where crypto runs | Private keys                                                  | Fit                                           |
| :------------------------------------- | :---------------- | :------------------------------------------------------------ | :-------------------------------------------- |
| **WASM in the browser** (`createChat`) | User's device     | Recovered with PIN into WASM memory; not sent to your backend | **Recommended for chat UIs**                  |
| **Native Chat XDK on a server**        | Your servers      | Key blob or passcode-backed recovery on the server            | Bots and automation—not end-user chat clients |

End users should **never** paste their encryption PIN into your backend, and your backend should **never** hold their identity private keys. If a third-party server receives a user's PIN or root private keys, that party can decrypt conversation keys wrapped to that identity **even after the user revokes OAuth access**. Client-side WASM avoids that class of failure for legitimate apps.

<Warning>
  Sharing a PIN or private key with a third party is like sharing a password for encrypted DMs. OAuth disconnect does **not** revoke keys the app already obtained. Prefer WASM so keys never leave the browser; document risks clearly when you cannot. See [Handling private keys](/xchat/handling-private-keys).
</Warning>

***

## Recommended architecture

Split **crypto** (browser) from **API transport** (your backend or direct X API with a user token):

```mermaid theme={null}
flowchart TB
    subgraph Browser
        UI[Chat UI]
        WASM[Chat XDK WASM<br/>encrypt / decrypt / sign]
        Keys[Private keys in memory<br/>after PIN unlock]
        UI --> WASM
        WASM --> Keys
    end

    subgraph Your backend optional
        API[API routes<br/>OAuth user token]
    end

    X[X API<br/>ciphertext only]

    UI -->|encrypted payloads| API
    API --> X
    UI -->|or user access token| X
```

| Layer                       | Responsibility                                                                                                        |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| **Browser UI**              | Render conversations; collect PIN **only in the client**; call Chat XDK WASM for encrypt/decrypt/sign                 |
| **Chat XDK WASM**           | Key generation, secure key backup (`setup` / `unlock`), message crypto                                                |
| **Your backend (optional)** | Hold the OAuth access token, proxy X Chat REST, mint Juicebox realm auth tokens—**never** receive PIN or private keys |
| **X API**                   | Public keys, wrapped conversation keys, encrypted events and media                                                    |

A common pattern (used by internal demos such as browser chat clients) is: **WASM + React (or similar) in the frontend**, **TypeScript [XDK](/xdks/typescript/overview) in Next.js (or other) API routes** so the browser never talks to `api.x.com` with a long-lived secret if you prefer not to. Crypto still runs only in the browser.

***

## Install the browser package

```bash theme={null}
npm install @xdevplatform/chat-xdk
npm install juicebox-sdk   # required for setup() / unlock() secure key backup
```

The compiled WASM engine ships inside `@xdevplatform/chat-xdk`; there is no separate Rust toolchain for consumers. Requires a modern browser (and Node.js 18+ if you share code with SSR—run crypto only on the client).

***

## Session flow (PIN once, keys stay in memory)

Do **not** prompt for the PIN on every message. Unlock **once per browser session**, keep the `Chat` instance in memory (module singleton, React context, etc.), then encrypt and decrypt against that unlocked instance.

```typescript theme={null}
import { createChat } from '@xdevplatform/chat-xdk';

// 1) Create once per page load (client component / browser only)
const chat = await createChat({
  juiceboxConfig: JSON.stringify(record.juicebox_config), // from GET public keys for the user
  getAuthToken: async (realmId) => {
    // Your backend mints a Juicebox realm token for this user + key version.
    // Do not send the user's PIN here—only realm auth for secure key backup.
    const res = await fetch(`/api/juicebox/token?realm=${encodeURIComponent(realmId)}`);
    if (!res.ok) throw new Error('Juicebox token fetch failed');
    return res.text();
  },
});

// 2) First-time identity: generate → register public keys with X → backup with PIN
// const payload = chat.generateKeypairs();
// await registerPublicKeysWithX(payload);  // POST /2/users/:id/public_keys
// await chat.setup(pin);                   // PIN never leaves the browser

// 3) Returning session: recover keys with PIN (once)
await chat.unlock(pin);
chat.setIdentity(userId, signingKeyVersion);
chat.setCacheKeys(true);
// Fetch participants' public keys from X, then:
chat.setSigningKeys(signingKeys);

// 4) Use for the whole SPA session—no more PIN prompts
const result = chat.decryptEvents(rawEvents);
const sendBody = chat.encryptMessage({ conversationId, text: 'Hello' });
// POST sendBody to your backend or X Chat send-message endpoint

// 5) On logout or "lock chat"
chat.lock(); // clears key material from the WASM instance
// chat.free(); // if you will not reuse this instance
```

### UX expectations

| Event                       | What to do                                                                                                                                                                                             |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **App open / hard reload**  | User enters PIN → `unlock` → keep instance for navigation within the SPA                                                                                                                               |
| **Send / receive / media**  | Call encrypt/decrypt on the **already unlocked** instance                                                                                                                                              |
| **Logout / switch account** | `lock()` or `free()`; drop references; clear any session state                                                                                                                                         |
| **Forgot PIN / lockout**    | Secure key backup enforces a guess limit; recovery may require key reset (new keypairs + re-register). See [Cryptography primer](/xchat/cryptography-primer#secure-key-backup-distributed-key-storage) |

<Tip>
  **Avoid re-prompting the PIN on every action.** Demo apps sometimes call `unlock` repeatedly for simplicity. Production UIs should unlock once, hold the instance in memory, and only ask for the PIN again after reload, logout, or `lock()`.
</Tip>

***

## What your server is allowed to see

| Allowed on the server                                             | Never send to the server                                                    |
| :---------------------------------------------------------------- | :-------------------------------------------------------------------------- |
| OAuth 2.0 user access token                                       | Encryption PIN / passcode                                                   |
| Juicebox **realm auth tokens** (short-lived, for backup protocol) | Identity or signing **private** keys                                        |
| Public key registration payloads                                  | Raw `export_keys` blobs for end-user identities (browser apps)              |
| Encrypted message and media payloads                              | Plaintext message bodies (unless the user is composing them only in the UI) |
| Conversation ids, event ids, metadata X already stores            | Anything that reconstructs the user's root key material                     |

Realm tokens for Juicebox are **not** the user's PIN. They authorize the backup protocol for that user and key version. Keep minting them on a backend that already holds the user OAuth context.

***

## Secure key backup in the browser

Client apps should use **secure key backup** (`setup` / `unlock` with a passcode), not a raw key file:

1. Load `juicebox_config` from the user's public-key record (`public_key.fields=juicebox_config`).
2. `createChat({ juiceboxConfig, getAuthToken })`.
3. First time: `generateKeypairs` → register public keys with X → `setup(pin)`.
4. Later: `unlock(pin)` on this device (or a new device with the same PIN).

The Chat XDK's browser path recovers keys into WASM and **does not expose raw private-key export on the public `createChat` surface**, so application JavaScript is not encouraged to pull root key bytes into the page. Prefer that model over hand-rolled `localStorage` key dumps.

Full registration and unlock steps: [Getting Started](/xchat/getting-started). Concepts: [Cryptography primer](/xchat/cryptography-primer).

***

## Browser hardening checklist

* Run Chat XDK only in **client** bundles (no SSR of unlocked keys).
* Treat the unlocked `Chat` instance like a live session secret: do not put it on `window`, do not log it, do not post it to analytics.
* Defend against **XSS**: CSP, careful `dangerouslySetInnerHTML` / markdown rendering, dependency hygiene. XSS in a chat app can reach keys in memory even when keys never hit the network.
* Use **HTTPS** everywhere; never mix crypto pages with insecure scripts.
* Prefer **minimal OAuth scopes**; request DM scopes only when needed and explain them in your product UI.
* On logout, call **`lock()`** / **`free()`** and discard the instance.

Storage recommendations (what not to put in `localStorage`, how to think about session persistence) are in [Handling private keys](/xchat/handling-private-keys#browser-session-persistence).

***

## Next steps

1. [Handling private keys](/xchat/handling-private-keys) — PIN warnings, storage, bots vs UI apps
2. [Getting Started](/xchat/getting-started) — full key registration and first message
3. [Chat XDK](/xchat/xchat-xdk) — API reference for `createChat`, encrypt, decrypt
4. [Real-time events](/xchat/real-time-events) — deliver ciphertext to the client for local decrypt


# How X Chat keeps your messages secure
Source: https://docs.x.com/xchat/cryptography-primer

A plain-language guide to how X Chat protects messages: keys, encryption, digital signatures, and secure backups. No cryptography background needed.

X Chat is encrypted: a user's messages, in plaintext, exist only on their devices. This page explains how it works.

<Note>
  **This page is informational. You do not need this knowledge to build (the [Chat XDK](/xchat/xchat-xdk) performs every operation here for you).**
</Note>

***

## The big picture

Let's look at the entire flow from account creation up to sending / receiving messages.

<Steps>
  <Step title="Account creation">
    Here the Chat XDK generates two keypairs on your device:

    * an **identity keypair**, for receiving secrets
    * a **signing keypair**, for proving authorship

    Private halves go to [secure key backup](#secure-key-backup-distributed-key-storage), which we detail later. The important thing here is these are recoverable only with your passcode; X cannot recover them.

    Public halves are published to the X backend via the **public key** API, with a signature tying the identity and signing keys together.
  </Step>

  <Step title="Conversation creation">
    To message you, a sender generates a fresh **conversation key**, a symmetric key that will encrypt the messages.

    They fetch your public key from the X backend, verify the signature on it, and encrypt the conversation key to your identity key.

    This is a crucial property of public key cryptography, anyone can encrypt to your public key; **only your private key can decrypt, and only you hold it**. So X can store and deliver the encrypted copy, but never open it. (For the exact schemes used, see the [glossary](#glossary).)

    Why don't we just encrypt the messages directly to your public key? Speed: public key encryption is much more expensive than symmetric key encryption, so exchanging a key enables better efficiency for subsequent messages.
  </Step>

  <Step title="Messaging">
    When someone messages you, you will receive the conversation key, encrypted with your identity public key, and the messages encrypted with the conversation key.

    You use your identity private key to decrypt the conversation key (again, only you hold this key) and then use the resulting conversation key to decrypt the messages.

    Every so often, keys in a conversation rotate (a new symmetric key is shared), for different reasons. Therefore, each conversation key has a version so participants can always know they are using the right key.
  </Step>

  <Step title="Signing">
    Encryption lets anyone send you a message, which only you can decrypt. Signing is, in some sense, the opposite, it lets you (and only you) sign a message, and anyone verify the signature. Practically, the private key is necessary for signing, and the public key can be used for verifying.

    In X Chat, every sender signs their message. Signatures prove both who signed the message and the exact bytes signed, so all recipients can verify that this exact message was what the sender typed. Again, the XDK handles this for you; we cover the details in [Signatures explained](#signatures-explained).
  </Step>
</Steps>

***

## Putting it together

X Chat composes three standard cryptographic tools, each doing the one job it is good at:

1. A **conversation key** encrypts messages: symmetric, fast enough for all message and media traffic.
2. An **identity keypair** delivers conversation keys to each participant without anyone else (including X) seeing them.
3. A **signing keypair** proves authorship: every message carries a signature recipients verify.

```mermaid theme={null}
flowchart TB
    subgraph "Message Encryption"
        A[Your Message] --> B[Encrypt with<br/>Conversation Key]
        B --> C[Encrypted Message]
    end

    subgraph "Key Delivery"
        D[Conversation Key] --> E[Wrap to Recipient's<br/>Identity Public Key]
        E --> F[Encrypted Key Copy<br/>for Recipient]
    end

    subgraph "Authentication"
        C --> G[Sign with Your<br/>Signing Private Key]
        G --> H[Signature]
    end
```

X transports and stores only **ciphertext and wrapped keys**, nothing it can open. The XDK does the cryptography; the [X Chat API](/xchat/introduction) registers keys and moves encrypted payloads ([Getting Started](/xchat/getting-started)).

The full cast:

| Key                  | Who holds it                                   | What it does                                    |
| :------------------- | :--------------------------------------------- | :---------------------------------------------- |
| **Identity keypair** | Private half: only you. Public half: published | Receives wrapped conversation keys              |
| **Signing keypair**  | Private half: only you. Public half: published | Signs messages and state changes; others verify |
| **Conversation key** | Every participant of one conversation          | Encrypts messages and media; versioned, rotates |

***

## A worked example

Let's walk through what actually happens when you create a group with Bob and Carol.

<Steps>
  <Step title="Generate the conversation key">
    The XDK generates a fresh random conversation key. So far it exists only in memory on your device.
  </Step>

  <Step title="Fetch and verify participant keys">
    Your app fetches Bob's and Carol's public keys from the X backend and verifies the signature on each. If a signature doesn't check out, you stop; never encrypt to a key you couldn't verify.
  </Step>

  <Step title="Wrap the key to each participant">
    The XDK wraps the conversation key three times: to Bob's identity public key, to Carol's, and to your own (so your other devices can read it too).
  </Step>

  <Step title="Sign the change">
    The XDK signs a payload describing exactly this change: the group, its members, the wrapped keys. Creating a group needs **two** [action signatures](#signed-state-changes-action-signatures); the XDK produces both for you.
  </Step>

  <Step title="Publish">
    Your app POSTs the wrapped copies and signatures to X. The server stores three encrypted blobs it cannot open. At no point did the raw conversation key leave your device!
  </Step>

  <Step title="Bob reads">
    Bob's XDK unwraps his copy with his identity private key, verifies the key change came from you, and holds the raw conversation key.
  </Step>
</Steps>

That's the one-time setup. From here, every message follows the same two flows:

**Sending.** The XDK encrypts your message with the current conversation key, signs it, and your app POSTs both to the **send message** endpoint. X stores and delivers bytes it cannot read.

**Receiving.** Ciphertext arrives via [webhooks or an activity stream](/xchat/real-time-events), or by reading conversation **events** for history. The XDK verifies the sender's signature first, then decrypts with your stored conversation key (if the key rotated, a **key change** event delivers your new wrapped copy). If verification fails, the message is rejected.

Implementation lives in [Getting Started](/xchat/getting-started) and the [Chat XDK](/xchat/xchat-xdk) reference.

***

## Secure key backup: distributed key storage

Earlier we said your private keys are saved to **secure key backup**, recoverable only with your passcode. Let's look at how that works, because it is the part people are most skeptical about: how can keys be backed up without X being able to read them?

### The problem with traditional key storage

| Approach                          | Problem                                                          |
| :-------------------------------- | :--------------------------------------------------------------- |
| Store on device only              | Lose the device = lose the keys = lose access to message history |
| Store in an ordinary cloud backup | The provider can access key material                             |
| Remember a long key               | People cannot memorize high-entropy secrets                      |

### How secure key backup solves it

X Chat uses the open-source [**Juicebox**](https://juicebox.xyz) protocol, which combines **threshold secret sharing** with passcode protection. The full protocol is specified there; the short version:

**Storing (once, at account creation).** The XDK splits your private keys into shares and distributes them to three **realms**, separate services isolated from one another. All three are operated by X, so isolation alone would not mean much. That is where hardware comes in: two of the realms live inside **hardware security modules** (HSMs), tamper-resistant hardware that will not give up its share to anyone, not even an X administrator with full server access. A share on its own reveals nothing, and recovery requires shares from **two of the three** realms, so every possible recovery goes through at least one HSM: there is no software-only path to your keys. The HSM software and the **key ceremony** that provisioned it are publicly documented.

**Recovering (new device).** You enter your passcode, and the XDK proves to each realm that you know it. The Juicebox protocol makes this possible without the passcode ever leaving your device. Each realm that verifies you releases its share of your keys, and once two of the three respond, the XDK puts your keys back together on your device.

**Guess limits.** Each realm allows at most **20 wrong passcode attempts**. On the 20th wrong attempt, your key share is deleted from the realm. This is hardware-enforced by the HSMs and protects against any brute-force attack.

```mermaid theme={null}
flowchart LR
    subgraph Storing
        A[Your Private Keys] --> B[Split into Shares]
        B --> C[Realm 1<br/>Share A · HSM]
        B --> D[Realm 2<br/>Share B · HSM]
        B --> E[Realm 3<br/>Share C]
    end

    subgraph Recovering
        F[Your Passcode + 2 of 3 Realms] --> G[Reconstruct Keys]
    end

    E ~~~ F
```

The result: you can recover your keys on a new device with just your passcode, no single realm ever holds the whole secret, and the hardware-backed realms enforce their limits even against X itself.

<Note>
  You do not configure any of this by hand. The Chat XDK includes the backup client, and realm configuration arrives from the X backend with your public-key record. Passcode storage and unlock are Chat XDK calls; see [initialize with existing keys](/xchat/getting-started#2-initialize-the-chat-xdk-with-existing-keys) and [create and register keys](/xchat/getting-started#3-create-and-register-keys-first-time-setup). Servers and bots often skip backup and use an exported key blob instead; protect it like a password.
</Note>

***

## Signatures explained

Every message's signature gives recipients two guarantees:

1. **Authenticity**: produced by the holder of the sender's signing private key
2. **Integrity**: the encrypted content was not modified after signing

If anything in the signed content changes, verification fails. Of course, this guarantee is only as strong as the secrecy of the signing key, which is why [key storage](#secure-key-backup-distributed-key-storage) matters so much.

**In your app.** The XDK signs when you encrypt and verifies when you decrypt. Rejection happens at both ends: X Chat itself rejects events it cannot verify, and the XDK does the same on receipt, **mandatory by default** (disabling this is not recommended). Details: [Chat XDK](/xchat/xchat-xdk).

### Signed state changes (action signatures)

Messages are not the only thing signed. Every change to a conversation (creating a group, adding members, rotating a key) must also carry **action signatures**: the sender signs a payload describing exactly what the change does, and the API rejects requests where these are missing or malformed. The XDK produces them for you.

**Why the server cannot fully verify a key change.** The server never holds the raw conversation key (that is the point), so it cannot check a signature over material it cannot see. It checks what it can, that the signed description matches the request, and recipients do the real cryptographic check when they unwrap the key change.

Events are immutable: one that fails verification is permanently invalid. See [Troubleshooting](/xchat/troubleshooting).

***

## Security properties

Here is what X Chat protects against, and just as important, what it does not.

### What X Chat protects against

| Threat                             | Protection                                                                 | Resting on                                                                     |
| :--------------------------------- | :------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
| **X reading message bodies**       | Content is encrypted before it reaches X                                   | Conversation keys never leave participants' devices unwrapped                  |
| **Network eavesdroppers**          | Transport security plus encrypted message content                          | Standard TLS, plus everything above                                            |
| **Message tampering**              | Signatures detect any modification                                         | Signature verification on every event                                          |
| **Sender impersonation**           | A valid signature requires the sender's signing private key                | Signing key secrecy, plus the key binding you verified                         |
| **Key theft from a backup server** | Shares are split across realms and passcode-gated, with a hard guess limit | No single realm can reconstruct keys; HSMs enforce the guess limit in hardware |

### What X Chat does not protect against, and why

| Limitation                               | The honest version                                                                                                                                                                                                                                                                                                                                                                  |
| :--------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **A compromised device**                 | An unlocked client holds plaintext and raw keys. No encryption design survives a compromised endpoint.                                                                                                                                                                                                                                                                              |
| **Metadata**                             | X must know who messaged whom, and when, to route ciphertext. Encryption hides the *what*, not the *who* or *when*.                                                                                                                                                                                                                                                                 |
| **No forward secrecy**                   | Conversation keys are wrapped to long-lived identity keys: an attacker with your identity private key can unwrap previously captured envelopes, and with them past ciphertext.                                                                                                                                                                                                      |
| **No automatic post-compromise healing** | Recovery works, but it is deliberate rather than automatic: removing an attacker rotates the conversation key, and recovering a compromised device usually includes generating a fresh identity key and new conversation keys, so even stolen keys read nothing new. What no rotation can do is rewrite the past, or protect you in the window before the compromise is dealt with. |

***

## Glossary

| Term                         | Definition                                                                                                                      |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| **Symmetric encryption**     | Same key encrypts and decrypts (used for messages and media)                                                                    |
| **Asymmetric encryption**    | Public key to encrypt, private key to decrypt (used to deliver conversation keys)                                               |
| **Public key**               | Safe to publish; used to encrypt *to* someone or verify their signatures                                                        |
| **Private key**              | Must stay secret; used to decrypt or sign                                                                                       |
| **ECDH**                     | Key *agreement*: two parties derive a shared secret from one's private key and the other's public key                           |
| **ECIES**                    | Hybrid encryption built on ECDH: derive a shared secret, encrypt symmetrically under it. How conversation keys are wrapped      |
| **ECDSA**                    | The elliptic-curve signature algorithm used for messages and action signatures                                                  |
| **P-256**                    | The elliptic curve (secp256r1) all X Chat keypairs use                                                                          |
| **Key binding**              | The published signature tying a user's identity key to their signing key; verified before wrapping anything to a fetched record |
| **Conversation key**         | Symmetric key shared by the participants of one conversation, versioned over time                                               |
| **Wrapping**                 | Encrypting one key under another; here, a conversation key under an identity public key                                         |
| **Threshold secret sharing** | Splitting a secret into shares so that only a sufficient subset can reconstruct it; fewer than the threshold learn nothing      |
| **Juicebox**                 | The open-source protocol behind secure key backup: passcode-gated threshold recovery with hard guess limits                     |
| **HSM**                      | Hardware security module: tamper-resistant hardware that holds a realm's share and enforces its guess limit                     |
| **Realm**                    | A separate, isolated secure key backup service holding one share of your key material                                           |

***

## Next steps

<CardGroup>
  <Card title="Getting Started" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/xchat/getting-started">
    Implement keys, send, and receive step by step
  </Card>

  <Card title="Chat XDK Reference" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/xchat/xchat-xdk">
    Encryption SDK methods and types
  </Card>

  <Card title="Introduction" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/xchat/introduction">
    Product overview and architecture
  </Card>

  <Card title="Real-time events" icon="bolt" href="/xchat/real-time-events">
    How encrypted events are delivered
  </Card>
</CardGroup>


# Get started: send your first encrypted message
Source: https://docs.x.com/xchat/getting-started

A hands-on tutorial that takes you from zero to your first encrypted X Chat message, in Python, TypeScript, Go, Rust, C#, or Java.

Send and receive encrypted direct messages on X: set up keys, initialize a conversation, send a message, and decrypt inbound traffic.

X Chat apps use two pieces together:

| Component                        | Role                                                                                                                                                                            |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **[Chat XDK](/xchat/xchat-xdk)** | Encryption, decryption, signing, and private key storage (secure key backup or a key blob)                                                                                      |
| **X API**                        | Public keys, conversation keys, messages, and events: via the [Python](/xdks/python/overview) or [TypeScript](/xdks/typescript/overview) XDK, or HTTPS with a user access token |

<Note>
  **Prerequisites**

  * [Developer account](https://developer.x.com/en/portal/petition/essential/basic-info) and an app configured for OAuth 2.0
  * User access token with `dm.read`, `dm.write`, `tweet.read`, and `users.read`
</Note>

***

## 1. Install dependencies

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install chatxdk xdk
    ```

    The PyPI package is `chatxdk`; import it as `chat_xdk`. Requires Python 3.10+.
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install @xdevplatform/chat-xdk @xdevplatform/xdk
    npm install juicebox-sdk   # optional peer dependency; required for setup()/unlock() secure key backup
    ```

    The compiled WASM engine ships inside `@xdevplatform/chat-xdk`; there is no build step. Requires Node.js 18+.
  </Tab>

  <Tab title="Rust">
    ```toml theme={null}
    [dependencies]
    # chat-xdk-core is not yet on crates.io; use the git dependency
    chat-xdk-core = { git = "https://github.com/xdevplatform/chat-xdk" }  # pin a release tag in production, e.g. tag = "vX.Y.Z"
    reqwest = { version = "0.12", features = ["blocking", "json"] }
    serde_json = "1"
    base64 = "0.22"

    # Required until thrift 0.24 is released on crates.io
    [patch.crates-io]
    thrift = { git = "https://github.com/apache/thrift.git", rev = "deb36fa409849de45973b04ffc3ce49d277ca90a" }
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/xdevplatform/chat-xdk/go/chatxdk
    ```

    Precompiled static libraries are included (macOS arm64/amd64, Linux amd64 glibc/musl): you need a C compiler but not Rust. Requires Go 1.21+.
  </Tab>

  <Tab title="C#">
    ```bash theme={null}
    dotnet add package XDevPlatform.ChatXdk
    ```

    The package is self-contained: native libraries for macOS (arm64, x64), Linux (x64), and Windows (x64) ship inside it. Requires .NET 8+.
  </Tab>

  <Tab title="Java">
    ```xml theme={null}
    <dependency>
      <groupId>com.x</groupId>
      <artifactId>chatxdk</artifactId>
      <!-- Use the latest version from https://central.sonatype.com/artifact/com.x/chatxdk -->
      <version>x.y.z</version>
    </dependency>
    ```

    Available on Maven Central. The jar bundles the native library for macOS (arm64, x64), Linux (x64), and Windows (x64); no `jna.library.path` setup is needed. Import from `com.x.chatxdk`. Requires JDK 17+.
  </Tab>
</Tabs>

Create an API client with your **user** OAuth 2.0 access token:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from xdk import Client

    client = Client(access_token="YOUR_OAUTH2_USER_TOKEN")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { Client } from '@xdevplatform/xdk';

    const client = new Client({ accessToken: 'YOUR_OAUTH2_USER_TOKEN' });
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let access_token = std::env::var("X_ACCESS_TOKEN")?;
    let http = reqwest::blocking::Client::new();
    let auth = format!("Bearer {access_token}");
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    accessToken := os.Getenv("X_ACCESS_TOKEN")
    httpClient := &http.Client{Timeout: 30 * time.Second}
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    using var http = new HttpClient();
    http.DefaultRequestHeaders.Authorization =
        new System.Net.Http.Headers.AuthenticationHeaderValue(
            "Bearer", Environment.GetEnvironmentVariable("X_ACCESS_TOKEN"));
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String accessToken = System.getenv("X_ACCESS_TOKEN");
    HttpClient http = HttpClient.newHttpClient();
    ```
  </Tab>
</Tabs>

***

## 2. Initialize the Chat XDK with existing keys

This step **loads keys you already have**: use it when this identity completed first-time setup before:

* **Secure key backup:** construct the SDK with the `juicebox_config` from your public-key record, then `unlock` with your passcode to recover the private keys (for example, on a new device).
* **Key blob:** `import_keys` with a blob you previously exported via `export_keys`, passing the registered key version alongside it (Rust and Go name this variant `import_keys_with_version` / `ImportKeysWithVersion`).

Then call **`set_identity(user_id, signing_key_version)`** once, with your user ID and your record's `public_key_version`. This stores the session identity: every later encrypt and prepare call signs as this identity, so you never pass a sender ID or signing key version per call.

**Setting up for the first time?** Construct the SDK the same way but skip `unlock`/`import_keys`, and continue to [step 3](#3-create-and-register-keys-first-time-setup) to create, back up, and register your keys.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import json
    from chat_xdk import Chat

    resp = client.chat.get_user_public_keys(
        "YOUR_USER_ID",
        public_key_fields=[
            "public_key_version", "public_key", "signing_public_key",
            "identity_public_key_signature", "juicebox_config",
        ],
    )
    record = resp.data[0]
    signing_key_version = str(record["public_key_version"])

    chat = Chat(json.dumps(record["juicebox_config"]))
    chat.unlock("YOUR_PASSCODE")  # recovers keys stored by setup() during first-time setup (step 3)
    # Or load a key blob instead of secure key backup:
    # chat.import_keys(blob, version=signing_key_version)
    chat.set_identity("YOUR_USER_ID", signing_key_version)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { createChat } from '@xdevplatform/chat-xdk';

    const resp = await client.chat.getUserPublicKeys('YOUR_USER_ID', {
      publicKeyFields: [
        'public_key_version', 'public_key', 'signing_public_key',
        'identity_public_key_signature', 'juicebox_config',
      ],
    });
    const record = resp.data[0];
    const signingKeyVersion = String(record.public_key_version);

    const chat = await createChat({
      juiceboxConfig: JSON.stringify(record.juicebox_config),
      getAuthToken: async (realmId) => getRealmTokenFromYourBackend(realmId),
    });
    await chat.unlock('YOUR_PASSCODE');
    chat.setIdentity('YOUR_USER_ID', signingKeyVersion);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use base64::{engine::general_purpose::STANDARD as B64, Engine};
    use chat_xdk_core::ChatCore;

    let chat = ChatCore::new();
    let blob = B64.decode(std::env::var("PRIVATE_KEYS_B64")?)?;
    let signing_key_version = std::env::var("SIGNING_KEY_VERSION").unwrap_or_else(|_| "1".into());
    chat.import_keys_with_version(&blob, &signing_key_version)?;
    chat.set_identity("YOUR_USER_ID", &signing_key_version);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import "github.com/xdevplatform/chat-xdk/go/chatxdk"

    chat := chatxdk.New()
    defer chat.Close()

    blob, err := chatxdk.Base64ToBytes(os.Getenv("PRIVATE_KEYS_B64"))
    if err != nil {
        log.Fatal(err)
    }
    signingKeyVersion := os.Getenv("SIGNING_KEY_VERSION")
    if signingKeyVersion == "" {
        signingKeyVersion = "1"
    }
    if err := chat.ImportKeysWithVersion(blob, signingKeyVersion); err != nil {
        log.Fatal(err)
    }
    if err := chat.SetIdentity(myUserID, signingKeyVersion); err != nil {
        log.Fatal(err)
    }
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    using ChatXdk;

    using var chat = new Chat();
    var signingKeyVersion = Environment.GetEnvironmentVariable("SIGNING_KEY_VERSION") ?? "1";
    chat.ImportKeys(Convert.FromBase64String(
        Environment.GetEnvironmentVariable("PRIVATE_KEYS_B64")!), signingKeyVersion);
    chat.SetIdentity(myUserId, signingKeyVersion);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.x.chatxdk.Chat;

    String signingKeyVersion = Optional.ofNullable(System.getenv("SIGNING_KEY_VERSION")).orElse("1");
    try (Chat chat = new Chat()) {
        chat.importKeys(Base64.getDecoder().decode(System.getenv("PRIVATE_KEYS_B64")), signingKeyVersion);
        chat.setIdentity(myUserId, signingKeyVersion);
    }
    ```
  </Tab>
</Tabs>

Server and bot samples often use a **key blob** (`export_keys` / `import_keys`). Client apps often use **secure key backup** (`setup` / `unlock` with a passcode). See the [Chat XDK](/xchat/xchat-xdk) reference for both paths.

<Note>
  **Bringing your own keys?** `import_keys` only accepts the opaque blob produced by `export_keys` from the Chat XDK. It is a versioned, private serialization of the full key state, not raw or PEM-encoded P-256 keys. You cannot construct this blob yourself: generate keys through `generate_keypairs` ([step 3](#3-create-and-register-keys-first-time-setup)), export the blob once, and store it base64-encoded. Hand-crafted or modified blobs fail to import.
</Note>

***

## 3. Create and register keys (first-time setup)

Skip this step if you loaded existing keys in [step 2](#2-initialize-the-chat-xdk-with-existing-keys). Otherwise, one-time setup for a new identity does **three things**:

1. **Create the keypairs**: `generate_keypairs` produces the identity and signing keypairs.
2. **Store the private keys**: `setup` with a passcode writes them to secure key backup (clients), or `export_keys` returns a key blob for you to store securely (servers and bots).
3. **Register the public keys**: POST the registration payload to the add-public-key endpoint so others can encrypt to you and verify your signatures.

Finish by calling `set_identity` with the registration's key version, so this session signs as the new identity.

<Tip>
  Ready-to-run one-time registration scripts for every binding live under [`chat-xdk/examples`](https://github.com/xdevplatform/chat-xdk/tree/main/examples) (Python, TypeScript, Go, Rust, C#, and Java). Use them instead of hand-rolling the flow below when you just need to onboard a new identity.
</Tip>

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from xdk.chat.models import AddUserPublicKeyRequest

    registration = chat.generate_keypairs()
    pk = registration.public_key
    client.chat.add_user_public_key(
        "YOUR_USER_ID",
        AddUserPublicKeyRequest(
            public_key={
                "identity_public_key_signature": pk.identity_public_key_signature,
                "public_key": pk.public_key,
                "public_key_fingerprint": pk.public_key_fingerprint,
                "registration_method": pk.registration_method,
                "signing_public_key": pk.signing_public_key,
                "signing_public_key_signature": pk.signing_public_key_signature,
            },
            version=registration.version,
            generate_version=registration.generate_version,
        ),
    )
    chat.setup("YOUR_PASSCODE")
    chat.set_identity("YOUR_USER_ID", str(registration.version or "1"))
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const registration = chat.generateKeypairs();
    const pk = registration.publicKey;
    await client.chat.addUserPublicKey('YOUR_USER_ID', {
      public_key: {
        identity_public_key_signature: pk.identityPublicKeySignature,
        public_key: pk.publicKey,
        public_key_fingerprint: pk.publicKeyFingerprint,
        registration_method: pk.registrationMethod,
        signing_public_key: pk.signingPublicKey,
        signing_public_key_signature: pk.signingPublicKeySignature,
      },
      version: registration.version,
      generate_version: registration.generateVersion,
    });
    await chat.setup('YOUR_PASSCODE');
    chat.setIdentity('YOUR_USER_ID', String(registration.version ?? '1'));
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let registration = chat.generate_keypairs()?;
    let body = serde_json::to_value(&registration)?;
    let resp = http
        .post(format!("https://api.x.com/2/users/{user_id}/public_keys"))
        .header("Authorization", &auth)
        .json(&body)
        .send()?;
    if !resp.status().is_success() {
        anyhow::bail!("register keys: {}", resp.text()?);
    }
    let _blob = chat.export_keys()?; // store securely
    let key_version = registration.version.clone().unwrap_or_else(|| "1".into());
    chat.set_identity(&user_id, &key_version);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    registration, err := chat.GenerateKeypairs()
    if err != nil {
        log.Fatal(err)
    }
    regJSON, _ := json.Marshal(registration)
    req, _ := http.NewRequest(http.MethodPost,
        "https://api.x.com/2/users/"+userID+"/public_keys",
        bytes.NewReader(regJSON))
    req.Header.Set("Authorization", "Bearer "+accessToken)
    req.Header.Set("Content-Type", "application/json")
    resp, err := httpClient.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    resp.Body.Close()
    privateKeys, _ := chat.ExportKeys() // store securely
    _ = privateKeys
    keyVersion := "1"
    if registration.Version != nil {
        keyVersion = *registration.Version
    }
    if err := chat.SetIdentity(userID, keyVersion); err != nil {
        log.Fatal(err)
    }
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    var registration = chat.GenerateKeypairs();
    var regJson = System.Text.Json.JsonSerializer.Serialize(registration);
    using var content = new StringContent(regJson, Encoding.UTF8, "application/json");
    using var regResp = await http.PostAsync(
        $"https://api.x.com/2/users/{Uri.EscapeDataString(userId)}/public_keys", content);
    regResp.EnsureSuccessStatusCode();
    var blob = chat.ExportKeys(); // store securely
    chat.SetIdentity(userId, registration.Version ?? "1");
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    var registration = chat.generateKeypairs();
    String regJson = new ObjectMapper().writeValueAsString(registration);
    HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create("https://api.x.com/2/users/" + userId + "/public_keys"))
        .header("Authorization", "Bearer " + accessToken)
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(regJson))
        .build();
    HttpResponse<String> regResp = http.send(req, HttpResponse.BodyHandlers.ofString());
    if (regResp.statusCode() >= 300) {
        throw new RuntimeException("register keys: " + regResp.body());
    }
    byte[] blob = chat.exportKeys(); // store securely
    chat.setIdentity(myUserId, registration.version != null ? registration.version : "1");
    ```
  </Tab>
</Tabs>

<Warning>
  Use a strong passcode for secure key backup. Losing the passcode or an unprotected key blob can prevent decrypting past messages.
</Warning>

***

## 4. Set up conversation keys

Call **`prepare_conversation_key_change`** with every participant's identity public key; the sender identity comes from the session you set in step 2. One call generates a fresh conversation key, encrypts it for each participant, and signs the change. POST the result to the **add conversation keys** endpoint (`POST /2/chat/conversations/{id}/keys`). The body needs `conversation_key_version`, `conversation_participant_keys` (SDK `encrypted_key` → API `encrypted_conversation_key`), and **`action_signatures`** (required; the API rejects the call without them). Keep the **raw** conversation key for sending.

The response returns the canonical conversation id (`data.conversation_id`: the hyphen-joined pair for a 1:1, or the g-prefixed id for a group) and the key change's `data.sequence_id`. Use that returned id for subsequent requests instead of reconstructing it client-side. The same call also **rotates** keys later: pass the existing conversation id to `prepare_conversation_key_change` and POST with the newer key version. Rotate when you suspect the conversation key was exposed. Rotation protects **future** messages only; messages encrypted under earlier key versions stay readable to anyone who holds those versions.

<Warning>
  **Verify fetched keys before wrapping.** `prepare_conversation_key_change` encrypts the fresh conversation key to whatever public keys you pass. Check each fetched record first with `verify_key_binding(identity, signing, signature)` (passing the record's `public_key`, `signing_public_key`, and `identity_public_key_signature` fields from the public-keys API) so a substituted identity key cannot receive the conversation key.
</Warning>

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    def public_key_input(user_id: str) -> dict:
        r = client.chat.get_user_public_keys(
            user_id, public_key_fields=["public_key_version", "public_key"]
        ).data[0]
        return {"user_id": user_id, "public_key": r["public_key"], "key_version": r["public_key_version"]}

    prepared = chat.prepare_conversation_key_change(
        [public_key_input("YOUR_USER_ID"), public_key_input("RECIPIENT_USER_ID")],
        # conversation_id=None for a new 1:1; pass the id to rotate later
    )
    resp = client.chat.add_conversation_keys(
        "RECIPIENT_USER_ID",
        {
            "conversation_key_version": prepared["conversation_key_version"],
            "conversation_participant_keys": [
                {
                    "user_id": pk["user_id"],
                    "encrypted_conversation_key": pk["encrypted_key"],
                    "public_key_version": pk["public_key_version"],
                }
                for pk in prepared["participant_keys"]
            ],
            "action_signatures": [
                {
                    "message_id": sig["message_id"],
                    "encoded_message_event_detail": sig["encoded_message_event_detail"],
                    "message_event_signature": {
                        "signature": sig["signature"],
                        "public_key_version": sig["public_key_version"],
                        "signature_version": sig["signature_version"],
                    },
                }
                for sig in prepared["action_signatures"]
            ],
        },
    )
    conversation_id = resp.data["conversation_id"]  # canonical id for later requests
    sequence_id = resp.data["sequence_id"]
    conv_key = prepared["conversation_key"]
    conv_key_version = prepared["conversation_key_version"]
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    async function publicKeyInput(userId: string) {
      const r = (await client.chat.getUserPublicKeys(userId, {
        publicKeyFields: ['public_key_version', 'public_key'],
      })).data[0];
      return { userId, publicKey: r.public_key, keyVersion: r.public_key_version };
    }

    // Omit conversationId for a new 1:1; pass the id to rotate later
    const prepared = chat.prepareConversationKeyChange({
      publicKeys: [
        await publicKeyInput('YOUR_USER_ID'),
        await publicKeyInput('RECIPIENT_USER_ID'),
      ],
    });
    const resp = await client.chat.addConversationKeys('RECIPIENT_USER_ID', {
      conversation_key_version: prepared.conversationKeyVersion,
      conversation_participant_keys: prepared.participantKeys.map((pk) => ({
        user_id: pk.userId,
        encrypted_conversation_key: pk.encryptedKey,
        public_key_version: pk.publicKeyVersion,
      })),
      action_signatures: prepared.actionSignatures.map((sig) => ({
        message_id: sig.messageId,
        encoded_message_event_detail: sig.encodedMessageEventDetail,
        message_event_signature: {
          signature: sig.signature,
          public_key_version: sig.publicKeyVersion,
          signature_version: sig.signatureVersion,
        },
      })),
    });
    const conversationId = resp.data.conversation_id; // canonical id for later requests
    const sequenceId = resp.data.sequence_id;
    const convKey = prepared.conversationKey;
    const convKeyVersion = prepared.conversationKeyVersion;
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // public_key_inputs: Vec<PublicKeyInput> from GET public keys
    // (user_id, public_key, key_version ← public_key_version)
    // New 1:1; set params.conversation_id = Some(id) to rotate later
    let prepared = chat.prepare_conversation_key_change(
        ConversationKeyChangeParams::new(public_key_inputs),
    )?;
    let participant_keys: Vec<_> = prepared
        .participant_keys
        .iter()
        .map(|pk| {
            serde_json::json!({
                "user_id": pk.user_id,
                "encrypted_conversation_key": pk.encrypted_key,
                "public_key_version": pk.public_key_version,
            })
        })
        .collect();
    let action_signatures: Vec<_> = prepared
        .action_signatures
        .iter()
        .map(|sig| {
            serde_json::json!({
                "message_id": sig.message_id,
                "encoded_message_event_detail": sig.encoded_message_event_detail,
                "message_event_signature": {
                    "signature": sig.signature,
                    "public_key_version": sig.public_key_version,
                    "signature_version": sig.signature_version,
                },
            })
        })
        .collect();
    let body = serde_json::json!({
        "conversation_key_version": prepared.conversation_key_version,
        "conversation_participant_keys": participant_keys,
        "action_signatures": action_signatures,
    });
    let resp: serde_json::Value = http
        .post(format!("https://api.x.com/2/chat/conversations/{recipient_id}/keys"))
        .header("Authorization", &auth)
        .json(&body)
        .send()?
        .json()?;
    // Canonical id for later requests
    let conversation_id = resp["data"]["conversation_id"].as_str().unwrap().to_string();
    // conversation_key is Option<XChatConversationKey>; encrypt_message wants owned bytes
    let conv_key = prepared.conversation_key.expect("key present").to_bytes();
    let conv_key_version = prepared.conversation_key_version;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    // KeyVersion comes from the public_key_version field on each record
    prepared, err := chat.PrepareConversationKeyChange(chatxdk.ConversationKeyChangeParams{
        PublicKeys: []chatxdk.PublicKeyInput{
            {UserID: myUserID, PublicKey: myIdentityPubB64, KeyVersion: myKeyVersion},
            {UserID: recipientID, PublicKey: theirIdentityPubB64, KeyVersion: theirKeyVersion},
        },
        // ConversationID empty for a new 1:1; pass the id to rotate later
    })
    var parts []map[string]string
    for _, pk := range prepared.ParticipantKeys {
        parts = append(parts, map[string]string{
            "user_id":                    pk.UserID,
            "encrypted_conversation_key": pk.EncryptedKey,
            "public_key_version":         pk.PublicKeyVersion,
        })
    }
    var sigs []map[string]any
    for _, sig := range prepared.ActionSignatures {
        sigs = append(sigs, map[string]any{
            "message_id":                   sig.MessageID,
            "encoded_message_event_detail": sig.EncodedMessageEventDetail,
            "message_event_signature": map[string]string{
                "signature":          sig.Signature,
                "public_key_version": sig.PublicKeyVersion,
                "signature_version":  sig.SignatureVersion,
            },
        })
    }
    body, _ := json.Marshal(map[string]any{
        "conversation_key_version":      prepared.ConversationKeyVersion,
        "conversation_participant_keys": parts,
        "action_signatures":             sigs,
    })
    req, _ := http.NewRequest(http.MethodPost,
        "https://api.x.com/2/chat/conversations/"+recipientID+"/keys",
        bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer "+accessToken)
    req.Header.Set("Content-Type", "application/json")
    resp, err := httpClient.Do(req)
    // Response data.conversation_id is the canonical id for later requests
    _ = resp
    convKey := prepared.ConversationKey
    convKeyVersion := prepared.ConversationKeyVersion
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    // KeyVersion comes from the public_key_version field on each record
    var prepared = chat.PrepareConversationKeyChange(new ConversationKeyChangeParams(new[] {
        new PublicKeyInput { UserId = myUserId, PublicKey = myPk, KeyVersion = myVer },
        new PublicKeyInput { UserId = recipientId, PublicKey = theirPk, KeyVersion = theirVer },
    })); // ConversationId null for a new 1:1; set it to rotate later
    var keysBody = new {
        conversation_key_version = prepared.ConversationKeyVersion,
        conversation_participant_keys = prepared.ParticipantKeys.Select(pk => new {
            user_id = pk.UserId,
            encrypted_conversation_key = pk.EncryptedKey,
            public_key_version = pk.PublicKeyVersion,
        }),
        action_signatures = prepared.ActionSignatures.Select(sig => new {
            message_id = sig.MessageId,
            encoded_message_event_detail = sig.EncodedMessageEventDetail,
            message_event_signature = new {
                signature = sig.Signature,
                public_key_version = sig.PublicKeyVersion,
                signature_version = sig.SignatureVersion,
            },
        }),
    };
    var json = System.Text.Json.JsonSerializer.Serialize(keysBody);
    using var content = new StringContent(json, Encoding.UTF8, "application/json");
    using var resp = await http.PostAsync(
        $"https://api.x.com/2/chat/conversations/{Uri.EscapeDataString(recipientId)}/keys",
        content);
    resp.EnsureSuccessStatusCode();
    var data = System.Text.Json.JsonDocument.Parse(await resp.Content.ReadAsStringAsync())
        .RootElement.GetProperty("data");
    string conversationId = data.GetProperty("conversation_id").GetString()!; // canonical id
    byte[] convKey = prepared.ConversationKey!;
    string convKeyVersion = prepared.ConversationKeyVersion;
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    // keyVersion comes from the public_key_version field on each record
    PublicKeyInput mine = new PublicKeyInput();
    mine.userId = myUserId; mine.publicKey = myIdentityPubB64; mine.keyVersion = myKeyVersion;
    PublicKeyInput theirs = new PublicKeyInput();
    theirs.userId = recipientId; theirs.publicKey = theirIdentityPubB64; theirs.keyVersion = theirKeyVersion;

    // conversationId stays null for a new 1:1; set it to rotate later
    PreparedConversationChange prepared =
        chat.prepareConversationKeyChange(new ConversationKeyChangeParams(List.of(mine, theirs)));

    List<Map<String, String>> parts = new ArrayList<>();
    for (var pk : prepared.participantKeys) {
        parts.add(Map.of(
            "user_id", pk.userId,
            "encrypted_conversation_key", pk.encryptedKey,
            "public_key_version", pk.publicKeyVersion));
    }
    List<Map<String, Object>> sigs = new ArrayList<>();
    for (var sig : prepared.actionSignatures) {
        sigs.add(Map.of(
            "message_id", sig.messageId,
            "encoded_message_event_detail", sig.encodedMessageEventDetail,
            "message_event_signature", Map.of(
                "signature", sig.signature,
                "public_key_version", sig.publicKeyVersion,
                "signature_version", sig.signatureVersion)));
    }
    ObjectMapper mapper = new ObjectMapper();
    String body = mapper.writeValueAsString(Map.of(
        "conversation_key_version", prepared.conversationKeyVersion,
        "conversation_participant_keys", parts,
        "action_signatures", sigs));
    HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create("https://api.x.com/2/chat/conversations/" + recipientId + "/keys"))
        .header("Authorization", "Bearer " + accessToken)
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();
    HttpResponse<String> resp = http.send(req, HttpResponse.BodyHandlers.ofString());
    JsonNode data = mapper.readTree(resp.body()).path("data");
    String conversationId = data.path("conversation_id").asText(); // canonical id
    byte[] convKey = prepared.conversationKey;
    String convKeyVersion = prepared.conversationKeyVersion;
    ```
  </Tab>
</Tabs>

***

## 5. Send a message

Encrypt with the **raw** conversation key from step 4. The SDK generates the message id (a UUID), embeds it in the signed event, and returns it on the payload; you never mint one yourself. On the send request, map:

| Chat XDK field                                                                | Request body field                |
| :---------------------------------------------------------------------------- | :-------------------------------- |
| `encrypted_content` / `encryptedContent` / `EncryptedContent`                 | `encoded_message_create_event`    |
| `encoded_event_signature` / `encodedEventSignature` / `EncodedEventSignature` | `encoded_message_event_signature` |
| Payload `message_id` / `messageId` / `MessageId`                              | `message_id`                      |

Use a **hyphenated** conversation id in the URL path when the API requires it (`:` → `-`). The SDK itself is flexible: `encrypt_message` and `encrypt_reply` accept the id in any form you hold (`A:B` from events, `A-B` from listings or URL paths in either order, or just the recipient's user id) and canonicalize it before signing. Group ids (prefixed with `g`) pass through unchanged.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from xdk.chat.models import SendMessageRequest

    # Sender identity resolves from set_identity (step 2)
    payload = chat.encrypt_message(
        "CONVERSATION_ID",
        "Hello!",
        conversation_key=conv_key,
        conversation_key_version=conv_key_version,
    )
    client.chat.send_message(
        "RECIPIENT_USER_ID",
        SendMessageRequest(
            message_id=payload.message_id,  # SDK-generated, embedded in the signed event
            encoded_message_create_event=payload.encrypted_content,
            encoded_message_event_signature=payload.encoded_event_signature,
        ),
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    // Sender identity resolves from setIdentity (step 2)
    const payload = chat.encryptMessage({
      conversationId: 'CONVERSATION_ID',
      text: 'Hello!',
      conversationKey: convKey,
      conversationKeyVersion: convKeyVersion,
    });
    await client.chat.sendMessage('RECIPIENT_USER_ID', {
      message_id: payload.messageId, // SDK-generated, embedded in the signed event
      encoded_message_create_event: payload.encryptedContent,
      encoded_message_event_signature: payload.encodedEventSignature,
    });
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use chat_xdk_core::EncryptMessageParams;

    // Sender identity resolves from set_identity (step 2)
    let payload = chat.encrypt_message(
        EncryptMessageParams::new(&conversation_id, "Hello!")
            .with_conversation_key(conv_key, &conv_key_version),
    )?;
    let body = serde_json::json!({
        // SDK-generated, embedded in the signed event
        "message_id": payload.message_id,
        "encoded_message_create_event": payload.encrypted_content,
        "encoded_message_event_signature": payload.encoded_event_signature,
    });
    let path_id = conversation_id.replace(':', "-");
    http.post(format!("https://api.x.com/2/chat/conversations/{path_id}/messages"))
        .header("Authorization", &auth)
        .json(&body)
        .send()?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    // Sender identity resolves from SetIdentity (step 2)
    payload, err := chat.EncryptMessage(chatxdk.EncryptMessageParams{
        ConversationID:         conversationID,
        Text:                   "Hello!",
        ConversationKey:        convKey,
        ConversationKeyVersion: convKeyVersion,
    })
    if err != nil {
        log.Fatal(err)
    }
    body, _ := json.Marshal(map[string]string{
        // SDK-generated, embedded in the signed event
        "message_id":                      payload.MessageID,
        "encoded_message_create_event":    payload.EncryptedContent,
        "encoded_message_event_signature": payload.EncodedEventSignature,
    })
    pathID := strings.ReplaceAll(conversationID, ":", "-")
    req, _ := http.NewRequest(http.MethodPost,
        "https://api.x.com/2/chat/conversations/"+pathID+"/messages",
        bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer "+accessToken)
    req.Header.Set("Content-Type", "application/json")
    resp, err := httpClient.Do(req)
    _ = resp
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    // Sender identity resolves from SetIdentity (step 2)
    var payload = chat.EncryptMessage(new EncryptMessageParams(conversationId, "Hello!") {
        ConversationKey = convKey,
        ConversationKeyVersion = convKeyVersion,
    });
    var sendJson = System.Text.Json.JsonSerializer.Serialize(new Dictionary<string, string> {
        // SDK-generated, embedded in the signed event
        ["message_id"] = payload.MessageId,
        ["encoded_message_create_event"] = payload.EncryptedContent,
        ["encoded_message_event_signature"] = payload.EncodedEventSignature,
    });
    using var content = new StringContent(sendJson, Encoding.UTF8, "application/json");
    var pathId = conversationId.Replace(':', '-');
    using var resp = await http.PostAsync(
        $"https://api.x.com/2/chat/conversations/{Uri.EscapeDataString(pathId)}/messages",
        content);
    resp.EnsureSuccessStatusCode();
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    // Sender identity resolves from setIdentity (step 2)
    EncryptMessageParams params = new EncryptMessageParams(conversationId, "Hello!");
    params.conversationKey = convKey;
    params.conversationKeyVersion = convKeyVersion;
    SendPayload payload = chat.encryptMessage(params);

    String pathId = conversationId.replace(':', '-');
    String sendJson = new ObjectMapper().writeValueAsString(Map.of(
        // SDK-generated, embedded in the signed event
        "message_id", payload.messageId,
        "encoded_message_create_event", payload.encryptedContent,
        "encoded_message_event_signature", payload.encodedEventSignature));
    HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create("https://api.x.com/2/chat/conversations/" + pathId + "/messages"))
        .header("Authorization", "Bearer " + accessToken)
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(sendJson))
        .build();
    http.send(req, HttpResponse.BodyHandlers.ofString());
    ```
  </Tab>
</Tabs>

<Note>
  The snippets pass the conversation key explicitly because in this flow you just created it in step 4. Once the key cache is on and a `decrypt_events` pass has verified the conversation's key ([step 6](#6-receive-and-decrypt)), `encrypt_message(conversation_id, text)` alone is enough: the SDK fills in the latest verified key. Retries should resend the **same** encrypted payload, so an id is never minted twice.
</Note>

***

## 6. Receive and decrypt

Use [webhooks or the activity stream](/xchat/real-time-events) for live traffic, or page conversation **events** for history.

* Live payload fields: `encoded_event`, optional `conversation_key_change_event`
* History: `GET /2/chat/conversations/{id}/events`; prefer **`decrypt_events`** on all events plus `meta.conversation_key_events`
* Decrypting needs the senders' **signing keys** so the SDK can verify who wrote each message. These are the other participants' *public* keys: fetch them from the same public-keys endpoint you used in step 4 and map the fields into `SigningKeyEntry` (the snippets below include the mapping)
* You can pass the signing keys (and, for `decrypt_event`, the conversation keys) on every call, **or** set two optional session stores once and use the short call forms. The snippets below use the stores: `set_signing_keys(entries)` holds the participants' keys, and `set_cache_keys(true)` (off by default) keeps each conversation's latest **signature-verified** key so later calls can omit key arguments. Both styles verify identically
* JavaScript uses camelCase event types (`message`); other languages use `"Message"` and snake\_case fields in JSON

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Once per process: fill the signing-key store and enable the key cache
    def signing_keys_for(user_id: str) -> list[dict]:
        resp = client.chat.get_user_public_keys(
            user_id,
            public_key_fields=[
                "public_key_version", "public_key", "signing_public_key", "identity_public_key_signature",
            ],
        )
        return [
            {
                "user_id": user_id,
                "public_key_version": r["public_key_version"],
                "public_key": r["signing_public_key"],
                "identity_public_key": r["public_key"],
                "identity_public_key_signature": r["identity_public_key_signature"],
            }
            for r in resp.data
        ]

    chat.set_signing_keys(
        signing_keys_for("YOUR_USER_ID") + signing_keys_for("RECIPIENT_USER_ID")
    )
    chat.set_cache_keys(True)

    # Initial load or pagination: batch decrypt. Conversation keys are
    # extracted from the KeyChange events in the batch; per-event failures
    # are collected in result["errors"], never raised.
    result = chat.decrypt_events(all_events_b64)
    for dm in result["messages"]:
        event = dm["event"]
        if event["type"] == "Message" and event["content"]["content_type"] == "Text":
            print(event["sender_id"], event["content"]["text"], event["verified"])

    # Live traffic: one event at a time
    def handle_payload(payload: dict):
        if payload.get("conversation_key_change_event"):
            # A rotation enters the key cache only after its signature
            # verifies, which is what decrypt_events does
            chat.decrypt_events([payload["conversation_key_change_event"]])
        event = chat.decrypt_event(payload["encoded_event"])  # raises on failure
        if event["type"] == "Message" and event["content"]["content_type"] == "Text":
            print(event["sender_id"], event["content"]["text"], event["verified"])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    // Once per process: fill the signing-key store and enable the key cache
    async function signingKeysFor(userId: string) {
      const resp = await client.chat.getUserPublicKeys(userId, {
        publicKeyFields: [
          'public_key_version', 'public_key', 'signing_public_key', 'identity_public_key_signature',
        ],
      });
      return resp.data.map((r: {
        public_key_version: string;
        public_key: string;
        signing_public_key: string;
        identity_public_key_signature: string;
      }) => ({
        userId,
        publicKeyVersion: r.public_key_version,
        publicKey: r.signing_public_key,
        identityPublicKey: r.public_key,
        identityPublicKeySignature: r.identity_public_key_signature,
      }));
    }

    chat.setSigningKeys([
      ...(await signingKeysFor('YOUR_USER_ID')),
      ...(await signingKeysFor('RECIPIENT_USER_ID')),
    ]);
    chat.setCacheKeys(true);

    // Initial load or pagination: batch decrypt. Conversation keys are
    // extracted from the KeyChange events in the batch; per-event failures
    // are collected in result.errors, never thrown.
    const result = chat.decryptEvents(allEventsB64);
    for (const dm of result.messages) {
      if (dm.event.type === 'message' && dm.event.content?.contentType === 'text') {
        console.log(dm.event.senderId, dm.event.content.text, dm.event.verified);
      }
    }

    // Live traffic: one event at a time
    function handlePayload(payload: {
      encoded_event: string;
      conversation_key_change_event?: string;
    }) {
      if (payload.conversation_key_change_event) {
        // A rotation enters the key cache only after its signature
        // verifies, which is what decryptEvents does
        chat.decryptEvents([payload.conversation_key_change_event]);
      }
      const event = chat.decryptEvent(payload.encoded_event); // throws on failure
      if (event.type === 'message' && event.content?.contentType === 'text') {
        console.log(event.senderId, event.content.text, event.verified);
      }
    }
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // Once per instance: fill the signing-key store (Vec<SigningKeyEntry>
    // from GET /2/users/{id}/public_keys) and enable the key cache
    chat.set_signing_keys(participant_signing_keys);
    chat.set_cache_keys(true);

    // Initial load: batch decrypt; per-event failures land in result.errors
    let result = chat.decrypt_events(&all_events_b64, &[]);

    // Live traffic: a rotation enters the key cache only after its
    // signature verifies, which is what decrypt_events does
    if let Some(kc) = key_change_b64.as_deref() {
        chat.decrypt_events(&[kc], &[]);
    }
    let event = chat.decrypt_event(&encoded_event, &Default::default(), &[])?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    // Once per instance: fill the signing-key store ([]SigningKeyEntry
    // from GET /2/users/{id}/public_keys) and enable the key cache
    if err := chat.SetSigningKeys(participantSigningKeys); err != nil {
        log.Fatal(err)
    }
    chat.SetCacheKeys(true)

    // Initial load: batch decrypt; per-event failures land in result.Errors
    result, err := chat.DecryptEvents(allEventsB64, nil)
    if err != nil {
        log.Fatal(err)
    }
    for _, dm := range result.Messages {
        if dm.Event.Type == "Message" {
            fmt.Println(dm.Event.AsMessage().Text())
        }
    }

    // Live traffic: a rotation enters the key cache only after its
    // signature verifies, which is what DecryptEvents does
    if keyChange != "" {
        chat.DecryptEvents([]string{keyChange}, nil)
    }
    event, err := chat.DecryptEvent(encodedEvent, nil, nil)
    if err == nil && event.Type == "Message" {
        fmt.Println(event.AsMessage().Text())
    }
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    // Once per instance: fill the signing-key store (SigningKeyEntry list
    // from GET /2/users/{id}/public_keys) and enable the key cache
    chat.SetSigningKeys(participantSigningKeys);
    chat.SetCacheKeys(true);

    // Initial load: batch decrypt; per-event failures land in result.Errors
    var result = chat.DecryptEvents(allEventsB64);
    foreach (var dm in result.Messages)
    {
        if (dm.Event.GetProperty("type").GetString() == "Message")
            Console.WriteLine(dm.Event.GetProperty("content").GetProperty("text").GetString());
    }

    // Live traffic: a rotation enters the key cache only after its
    // signature verifies, which is what DecryptEvents does
    if (!string.IsNullOrEmpty(keyChangeB64))
        chat.DecryptEvents(new[] { keyChangeB64 });
    var evt = chat.DecryptEvent(encodedEvent);  // throws on failure
    if (evt.GetProperty("type").GetString() == "Message")
        Console.WriteLine(evt.GetProperty("content").GetProperty("text").GetString());
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    // Once per instance: fill the signing-key store (SigningKeyEntry list
    // from GET /2/users/{id}/public_keys) and enable the key cache
    chat.setSigningKeys(participantSigningKeys);
    chat.setCacheKeys(true);

    // Initial load: batch decrypt; per-event failures land in result.errors
    DecryptEventsResult result = chat.decryptEvents(allEventsB64, null);
    for (DecryptedMessage dm : result.messages) {
        if ("Message".equals(dm.event.path("type").asText())) {
            System.out.println(dm.event.path("content").path("text").asText());
        }
    }

    // Live traffic: a rotation enters the key cache only after its
    // signature verifies, which is what decryptEvents does
    if (keyChangeB64 != null && !keyChangeB64.isEmpty()) {
        chat.decryptEvents(List.of(keyChangeB64), null);
    }
    JsonNode evt = chat.decryptEvent(encodedEvent, (Map<String, byte[]>) null, null);
    if ("Message".equals(evt.path("type").asText())) {
        System.out.println(evt.path("content").path("text").asText());
    }
    ```
  </Tab>
</Tabs>

<Note>
  **Serverless or multi-instance?** The signing-key store and key cache live in the SDK instance's memory. Where that doesn't fit (one invocation decrypts, another sends), pass keys explicitly instead: `decrypt_events(events, signing_keys)`, `decrypt_event(event_b64, conversation_keys, signing_keys)`, and the `conversation_key`/`conversation_key_version` overrides on the encrypt methods. Persist the `conversation_keys` returned by `decrypt_events` yourself and pass them back in.
</Note>

Complete poll-and-reply bots for every language: [chat-xdk/examples](https://github.com/xdevplatform/chat-xdk/tree/main/examples).

***

## Best practices

* Keep the signing-key store fresh: re-call `set_signing_keys` with the full participant set when a sender registers a new key version, and refresh on signature verification failures
* Deduplicate live deliveries with `event_uuid`


# Create encrypted group conversations in X Chat
Source: https://docs.x.com/xchat/groups

Build group conversations in X Chat: create a group, add or remove members, and set an encrypted name and avatar, all with the same security as 1:1 chats.

Group chats use the **same encryption model** as 1:1 X Chat: one **conversation key** shared by members, wrapped to each member's **identity public key**, with messages encrypted and signed by the Chat XDK. What changes is **membership**, **how you create the conversation**, and often **encrypted title/avatar** fields on the conversation.

1:1 flows are in [Getting Started](/xchat/getting-started). Endpoint details are under **API reference → Conversations and messages**.

***

## How groups differ from 1:1

| Topic        | 1:1                                      | Group                                                                        |
| :----------- | :--------------------------------------- | :--------------------------------------------------------------------------- |
| Identity     | Often addressed by peer user id in paths | Conversation id typically starts with `g`                                    |
| Create       | Keys + messaging to a user               | Create / initialize group APIs, then keys                                    |
| Participants | You + one peer                           | Many users; membership can change                                            |
| Metadata     | Minimal                                  | Name, avatar, etc. may be **ciphertext** (decrypt with the conversation key) |
| Key rotation | Less frequent                            | Common when people join or leave                                             |

Crypto is still: **Chat XDK** for keys and payloads; **X API** to create the group, publish participant key wraps, send messages, and load events.

***

## Create the group and establish keys

1. Mint the group id with `POST /2/chat/conversations/group/initialize`: the response's `data.conversation_id` is the g-prefixed id you use everywhere below.
2. Load each member's identity public key and `public_key_version` (`GET` public-key routes under **Encryption keys**; [`GET /2/users/public_keys`](/x-api/users/get-public-keys-for-multiple-users) fetches several users in one request). Verify each record with `verify_key_binding` before using it (see the warning in [Getting Started](/xchat/getting-started#4-set-up-conversation-keys)).
3. Run **`prepare_group_create`** once, with **all** members (including yourself), the g-prefixed id, and the member/admin id lists. One call generates the conversation key, wraps it for every member, and signs the create with the session identity from `set_identity`. It returns **two** action signatures (the conversation-key change and the group create).
4. `POST /2/chat/conversations/group` with the group members/admins, `conversation_key_version`, `conversation_participant_keys` (SDK **`encrypted_key`** → API **`encrypted_conversation_key`**), and **both** `action_signatures`. Validation failures come back as stable, human-readable messages, for example `"Too many members: adding these members would exceed the allowed group size."` or `"Cannot add all members: one or more of the requested members cannot be added to this conversation."`.
5. Keep the **raw** conversation key and **version** for encrypt/decrypt.

`prepare_group_create` signs the `title` and `avatar_url` you pass in and embeds them verbatim in the group-create event. The server matches those against your request, so the `group_name` / `group_avatar_url` values in the POST body must be **byte-identical** to what you passed the SDK; otherwise the call fails signature validation.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # chat has keys loaded and set_identity called (see Getting Started)
    prepared = chat.prepare_group_create(
        member_public_keys,
        group_id,  # g-prefixed id from POST /2/chat/conversations/group/initialize
        member_ids, admin_ids, title="Project team",
    )
    # POST /2/chat/conversations/group with group_members, group_admins,
    # conversation_key_version, conversation_participant_keys, and BOTH
    # entries of prepared["action_signatures"]
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    // chat has keys loaded and setIdentity called (see Getting Started)
    const prepared = chat.prepareGroupCreate({
      publicKeys: memberPublicKeys,
      conversationId: groupId, // g-prefixed id from POST /2/chat/conversations/group/initialize
      memberIds, adminIds, title: 'Project team',
    });
    // prepared.actionSignatures has two entries; send both
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // chat has keys loaded and set_identity called (see Getting Started)
    let mut params = GroupCreateParams::new(
        member_public_keys, &group_id, member_ids, admin_ids,
    );
    params.title = Some("Project team".into());
    let prepared = chat.prepare_group_create(params)?;
    // prepared.action_signatures has two entries; send both
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    // chat has keys loaded and SetIdentity called (see Getting Started)
    prepared, err := chat.PrepareGroupCreate(chatxdk.GroupCreateParams{
        PublicKeys: memberPublicKeys, ConversationID: groupID,
        MemberIDs: memberIDs, AdminIDs: adminIDs, Title: "Project team",
    })
    // prepared.ActionSignatures has two entries; send both
    _ = prepared
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    // chat has keys loaded and SetIdentity called (see Getting Started)
    var prepared = chat.PrepareGroupCreate(
        new GroupCreateParams(memberPublicKeys, groupId, memberIds, adminIds)
        {
            Title = "Project team",
        });
    // prepared.ActionSignatures has two entries; send both
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    // chat has keys loaded and setIdentity called (see Getting Started)
    GroupCreateParams params =
        new GroupCreateParams(memberPublicKeys, groupId, memberIds, adminIds);
    params.title = "Project team";
    PreparedConversationChange prepared = chat.prepareGroupCreate(params);
    // prepared.actionSignatures has two entries; send both
    ```
  </Tab>
</Tabs>

The body mapping for participant keys and action signatures (`message_id`, `encoded_message_event_detail`, nested `message_event_signature`) is the same as the keys POST in [Getting Started: conversation keys](/xchat/getting-started#4-set-up-conversation-keys).

When membership changes, call **`prepare_group_members_change`** with the new member ids plus the current roster (members, admins, pending members, and the current title/avatar/TTL if set). It rotates the conversation key and, like group create, returns **two** action signatures. POST all of it to **add members** (`POST /2/chat/conversations/{id}/members`). Then expect **key-change** traffic: treat it like [key rotation in Getting Started](/xchat/getting-started#6-receive-and-decrypt) (`extract_conversation_keys` / `decrypt_events`, then encrypt with the latest version).

Because `prepare_group_members_change` generates a **fresh** conversation key wrapped only to the roster you pass, new members receive the new key version and cannot decrypt messages sent under earlier versions. The reverse is not true: rotation never revokes access to **earlier** versions; anyone who already holds an old key can still read the messages encrypted under it. If you suspect a conversation key was exposed, rotate with `prepare_conversation_key_change`; this protects future messages only.

***

## Encrypted group metadata

Some conversation fields (for example display **name** or **avatar URL**) may arrive **encrypted** under the conversation key. That is **not** `encrypt_message`; it is the generic Chat XDK **`encrypt` / `decrypt`** pair (UTF-8 string in, base64 ciphertext out, with the **raw** conversation key).

Whether a given field is stored encrypted is decided by the client that writes it: `prepare_group_create` signs and sends the title exactly as you provide it (the conversation key does not exist until that call generates it, so a create-time title cannot be encrypted under it). When you read a conversation whose fields are ciphertext, decrypt them with `decrypt` and the key version that was active when the field was written.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Decrypt a field from the conversation object (name may vary by API shape)
    group_name = chat.decrypt(conversation["group_name"], raw_conv_key)

    # Encrypt before update if your API accepts ciphertext metadata
    encrypted_name = chat.encrypt("Project team", raw_conv_key)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const groupName = chat.decrypt(conversation.groupName, rawConvKey);
    const encryptedName = chat.encrypt('Project team', rawConvKey);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // conv_key: &XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
    let group_name = chat.decrypt(&conversation_group_name_b64, &conv_key)?;
    let encrypted_name = chat.encrypt("Project team", &conv_key)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    groupName, err := chat.Decrypt(conversationGroupNameB64, rawConvKey)
    encryptedName, err := chat.Encrypt("Project team", rawConvKey)
    _ = groupName
    _ = encryptedName
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    string groupName = chat.Decrypt(conversationGroupNameB64, rawConvKey);
    string encryptedName = chat.Encrypt("Project team", rawConvKey);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String groupName = chat.decrypt(conversationGroupNameB64, rawConvKey);
    String encryptedName = chat.encrypt("Project team", rawConvKey);
    ```
  </Tab>
</Tabs>

Use the **current** conversation key version that applies to that metadata. If keys rotated, decrypt with the version that was active when the field was written (or follow product rules if metadata is always rewritten on rotation).

***

## Messages and events

Sending and receiving in a group is the same as 1:1 once you have the raw conversation key:

* **Send:** `encrypt_message` → send-message API ([Getting Started](/xchat/getting-started#5-send-a-message))
* **Receive:** events API or [real-time delivery](/xchat/real-time-events) → `decrypt_event` / `decrypt_events`
* **Media:** [Media](/xchat/media) with the group conversation id

Always encrypt with the **latest** key version after a membership-driven rotation.

### Key changes from departed members

A group's key-change events are signed by whoever performed them, often the creator or an admin. If that member later **leaves the group** (or deactivates), the public-keys endpoints stop returning their keys, so the verified decrypt path (`decrypt_events` with signing keys) fails on those key-change events with `signature missing or no matching signing key`. The events are not corrupt; the verification material is simply no longer served.

Long-lived groups should expect this and fall back to **`extract_conversation_keys`** for key-change events that cannot be verified. This path skips the signature check and recovers the conversation key by decrypting it with your identity key. The security model holds because:

* Only key material that was **encrypted to your identity key** can be recovered at all; a third party cannot inject a key you can read
* Every **message** is still signature-verified against its own sender, so message authorship is unaffected

Keep the verified path first: use `decrypt_events` (which also feeds the SDK's key cache when `set_cache_keys(true)` is enabled), and reach for `extract_conversation_keys` only for the key-change events it rejects.

***

## Checklist

1. Mint the g-prefixed id with `POST /2/chat/conversations/group/initialize`
2. `prepare_group_create` with **every** member; POST participant key wraps and **both** action signatures to `POST /2/chat/conversations/group`
3. Cache raw key + version; update on key-change events
4. On membership changes, `prepare_group_members_change` (two signatures) → `POST /2/chat/conversations/{id}/members`
5. Decrypt group metadata with `decrypt` when fields are ciphertext
6. Send/receive with the same patterns as 1:1


# Best practices for handling X Chat private keys and PINs
Source: https://docs.x.com/xchat/handling-private-keys

Treat encryption PINs and private keys like root credentials: never share them with third parties, never put them on your servers for UI apps, and store them only with secure key backup or a hardened secret store.

X Chat identity and signing **private keys** are the root of a user's encrypted messaging identity. Anyone who holds them can unwrap conversation keys delivered to that identity and sign as that user for chat. Treat the encryption **PIN / passcode** the same way: it recovers those keys from secure key backup.

This page covers rules for every app type. For the recommended client architecture, see [Building UI apps with WASM](/xchat/building-ui-apps-with-wasm).

***

## Critical warning for users and app builders

<Warning>
  **Never ask end users to share their encryption PIN or private keys with a third-party server, support agent, or “helper” app.**

  The PIN unlocks **root identity keys**. A party that obtains the PIN (or the private key blob) can:

  * Decrypt conversation keys wrapped to that identity (and therefore message history they can obtain as ciphertext)
  * Continue to send and receive as that cryptographic identity
  * Keep that ability **even if the user later revokes OAuth** for the app

  Revoking OAuth stops API access for that app's tokens. It does **not** invalidate private keys the user already gave away. Prefer architectures where the PIN is entered only into **on-device** crypto ([WASM in the browser](/xchat/building-ui-apps-with-wasm) or a native client using the Chat XDK).
</Warning>

### Product and docs copy you should show

If your app requests DM-related OAuth scopes (`dm.read`, `dm.write`, and related scopes), pair the OAuth consent screen with clear product language:

* Encryption keys stay on the user's device when you use the official client SDK path.
* Users should never type their X Chat PIN into a website that forwards it to a backend.
* Legitimate integrations use the [Chat XDK](/xchat/xchat-xdk) so PIN-backed recovery and crypto run locally (for browsers: WASM + secure key backup).
* A malicious app that obtains private keys can exfiltrate them; there is no server-side “revoke this key” for a pure client-held root key today—design so users never need to hand root keys to you.

***

## What counts as sensitive key material

| Material                          | Sensitivity | Notes                                                                                                                |
| :-------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------- |
| **Encryption PIN / passcode**     | Critical    | Recovers private keys from [secure key backup](/xchat/cryptography-primer#secure-key-backup-distributed-key-storage) |
| **Identity private key**          | Critical    | Unwraps conversation keys for this user                                                                              |
| **Signing private key**           | Critical    | Proves authorship of messages and state changes                                                                      |
| **`export_keys` blob**            | Critical    | Opaque full private-key state from the Chat XDK; treat like a password file                                          |
| **Unwrapped conversation keys**   | High        | Decrypt messages in one conversation (versioned; still sensitive)                                                    |
| **OAuth access / refresh tokens** | High        | API access only—not a substitute for chat private keys, and not revoked by deleting keys                             |
| **Juicebox realm auth tokens**    | Medium      | Authorize backup protocol for a user/key version; not the PIN                                                        |
| **Public keys**                   | Public      | Safe to fetch and store                                                                                              |

***

## Choose the right key path by app type

| App type                                    | Recommended key path                                                                                | Do not                                                                          |
| :------------------------------------------ | :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| **User-facing web UI**                      | Browser [WASM Chat XDK](/xchat/building-ui-apps-with-wasm) + `setup` / `unlock` (secure key backup) | Send PIN or private keys to your servers; store raw key blobs in `localStorage` |
| **Native mobile / desktop client**          | Chat XDK on device + secure key backup or OS keystore-backed blob                                   | Sync unencrypted key blobs to your cloud                                        |
| **Bot / automation on your infrastructure** | `export_keys` blob in a **secret manager** or HSM; load with `import_keys`                          | Commit blobs to git; log them; embed in client-side JS                          |
| **Server that only moves ciphertext**       | No private keys at all—proxy encrypted payloads                                                     | Decrypt “for convenience” on the server for UI users                            |

Client apps should prefer **secure key backup**. Servers and bots often use an exported key blob. Details: [Getting Started](/xchat/getting-started#2-initialize-the-chat-xdk-with-existing-keys).

***

## Rules for private keys and PINs

### Do

* **Collect the PIN only in trusted client UI** that feeds the Chat XDK (`unlock` / `setup`) on the same device.
* **Keep keys in memory only while needed.** After unlock, reuse the same Chat instance for the session; call `lock()` or `free()` on logout.
* **Zeroize PIN buffers when the API allows** (for example pass a `Uint8Array` PIN in JS so you can clear it after `unlock`).
* **Store bot key blobs in a secret manager** (or HSM), encrypt at rest, restrict IAM, rotate process credentials often.
* **Log carefully:** never log PINs, private keys, key blobs, unwrapped conversation keys, or full secure-backup responses.
* **Defend the client:** XSS, malicious extensions, and compromised dependencies can read in-memory keys even when the network path is clean.

### Do not

* **Do not** email, screenshot, or ticket a PIN or key blob.
* **Do not** put private keys or PINs in query strings, analytics, error trackers, or CDN logs.
* **Do not** ship end-user private keys to “make the backend simpler.”
* **Do not** confuse **OAuth revoke** with **key revoke**. Disconnecting an app does not erase keys a user already exported or typed into a hostile client.
* **Do not** store raw `export_keys` output in `localStorage` or unencrypted IndexedDB for production UI apps.

***

## Browser session persistence

Production browser apps should optimize for **security first**, then UX:

| Strategy                                           | Security                                   | UX                                              | Recommendation                 |
| :------------------------------------------------- | :----------------------------------------- | :---------------------------------------------- | :----------------------------- |
| **Unlock once per page load; hold Chat in memory** | Strong                                     | PIN after every full reload; no PIN per message | **Default recommendation**     |
| **Re-prompt PIN on every message**                 | Strong but noisy                           | Poor                                            | Avoid (demo-only anti-pattern) |
| **Plaintext or base64 key blob in `localStorage`** | Weak (any XSS or shared device reads keys) | Convenient                                      | **Do not use in production**   |
| **PIN-gated secure key backup only** (Juicebox)    | Strong; guess-limited recovery             | PIN on new device / reload                      | **Preferred durable storage**  |

Internal demos sometimes export keys to `localStorage` for convenience. That is fine for throwaway prototypes; it is **not** a production pattern. Prefer:

1. `createChat` + `unlock(pin)` after reload.
2. Module-level or framework context holding the unlocked instance for SPA navigation.
3. `lock()` when the tab logs out or the user locks the app.

If you add extra “stay unlocked on this device” behavior, wrap any persisted material with **Web Crypto** (non-extractable keys where possible), bind it to the user session, and still never upload that material to your servers. The durable recovery path remains the user's PIN and secure key backup—not a second copy of the root key on your infrastructure.

***

## OAuth scopes vs encryption keys

These are separate control planes:

```mermaid theme={null}
flowchart LR
    subgraph OAuth
        T[Access token]
        T --> API[X Chat HTTP API]
    end

    subgraph Crypto
        PIN[User PIN]
        PK[Private keys]
        PIN --> PK
        PK --> E[Encrypt / decrypt / sign]
    end

    API -->|ciphertext| E
```

* **OAuth** authorizes API calls (list conversations, post ciphertext, fetch events).
* **Private keys** authorize cryptographic access to message contents.

A complete product should:

1. Request only the DM scopes it needs.
2. Explain why DM access is required.
3. Run crypto **on device** so OAuth never becomes a channel for collecting PINs.
4. Stop holding tokens on logout; separately `lock()` chat keys.

***

## Operational checklist

* [ ] No PIN or private key fields on server request bodies for UI flows
* [ ] Secure key backup (`setup` / `unlock`) for clients; secret manager for bot blobs
* [ ] Unlocked Chat instance scoped to one user session; cleared on logout
* [ ] Logging and APM scrubbed of secrets
* [ ] CSP and XSS controls on any page that can unlock chat
* [ ] User-facing copy: never share PIN with third parties
* [ ] Incident plan: if a bot blob leaks, rotate keys / re-register and treat historical ciphertext as exposed to the holder of the old key

***

## Related reading

* [Building UI apps with WASM](/xchat/building-ui-apps-with-wasm) — client architecture
* [Cryptography primer](/xchat/cryptography-primer) — identity keys, conversation keys, secure key backup
* [Getting Started](/xchat/getting-started) — register keys and send a message
* [Chat XDK](/xchat/xchat-xdk) — API reference
* [Fundamentals: Security](/fundamentals/security) — OAuth and API credential hygiene


# Send encrypted direct messages with the X Chat API
Source: https://docs.x.com/xchat/introduction

Learn what the X Chat API offers: send and receive encrypted direct messages on X, with the Chat XDK handling the hard parts for you.

The **X Chat API** lets you send and receive **encrypted** direct messages on X. Message bodies are encrypted on the client; X routes ciphertext and cannot read plaintext content. Messages are also **signed** so recipients can verify the sender.

***

## What you need in your app

| Piece                            | Responsibility                                                                                                              |
| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| **[Chat XDK](/xchat/xchat-xdk)** | Generate keys, encrypt/decrypt, sign/verify, optional passcode-protected secure key backup (Python, JS, Rust, Go, C#, Java) |
| **X API access**                 | Public keys, conversation keys, messages, events, media: via **[XDK](/xdks/python/overview)** (Python/TypeScript) or HTTPS  |
| **Delivery**                     | [Webhooks or activity stream](/xchat/real-time-events) for live events; events API for history                              |

Follow **[Getting Started](/xchat/getting-started)** for a full implementation. For concepts only, see the **[Cryptography primer](/xchat/cryptography-primer)**.

***

## How encryption works (overview)

1. Create **identity** and **signing** keypairs; store private keys securely (secure key backup or protected blob).
2. **Publish public keys** so others can exchange conversation keys with you and verify signatures.
3. Share a **conversation key** by posting encrypted copies for each participant.
4. **Encrypt and sign** outbound messages; send only ciphertext to X.
5. **Receive** ciphertext via webhooks, stream, or event history.
6. **Verify and decrypt** with the Chat XDK.

***

## Useful endpoints

Grouped under **API reference** in the sidebar, including:

* Public keys: register and fetch
* Conversations and messages: list/get conversations, add/rotate keys, events, send, typing, read, group membership
* Media: upload and download encrypted attachments ([guide](/xchat/media))

***

## Auth notes

Use **OAuth 2.0 user context** with DM-related scopes (`dm.read`, `dm.write`, plus `users.read` / `tweet.read` as required; `media.write` for uploads). X Chat activity for a user requires that user's authorization. Secure key backup configuration is returned on **your** public-key record (`juicebox_config` field); see Getting Started.

***

## Next steps

1. [Cryptography primer](/xchat/cryptography-primer): optional background on encryption concepts
2. [Getting Started](/xchat/getting-started): implement keys, send, and receive
3. [Chat XDK](/xchat/xchat-xdk): encryption SDK reference
4. [Building UI apps with WASM](/xchat/building-ui-apps-with-wasm) and [Handling private keys](/xchat/handling-private-keys): keep keys on-device and treat PINs as root credentials
5. [Real-time events](/xchat/real-time-events), [Media](/xchat/media), or [Troubleshooting](/xchat/troubleshooting) when you need those topics


# Send images and files in X Chat
Source: https://docs.x.com/xchat/media

Share images and file attachments in your encrypted chats: encrypt, upload, send, download, and decrypt media with the Chat XDK.

Images and other files use the **same conversation key** as text. Encrypt bytes with the Chat XDK (`encrypt_stream` / `decrypt_stream`), upload via the **`/2/chat/media/upload`** routes (sidebar **API reference → Media**), then attach **`media_hash_key`** on `encrypt_message`.

Include **`media.write`** with your DM scopes when uploading. Use hyphenated conversation ids in paths (`:` → `-`). Prefer MIME/dimensions from **decrypted** bytes.

This path is **not** the Posts media model (`expansions=attachments.media_keys`, `media.fields=variants`, etc.). Those parameters apply to **Posts**; encrypted X Chat blobs are addressed by **`media_hash_key`** and X Chat media download.

```mermaid theme={null}
flowchart LR
    A[Plain bytes] --> B[encrypt_stream]
    B --> C[Upload 3 steps]
    C --> D[media_hash_key]
    D --> E[encrypt_message + send]
    F[GET media] --> G[decrypt_stream]
    G --> H[Plain bytes]
```

***

## Encrypt

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from chat_xdk import detect_mime_type, detect_image_dimensions

    with open("photo.jpg", "rb") as f:
        plaintext = f.read()

    mime = detect_mime_type(plaintext)
    dims = detect_image_dimensions(plaintext)
    width, height = dims if dims else (0, 0)

    encrypted_blob = chat.encrypt_stream(plaintext, raw_conv_key)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { detectMimeType, detectImageDimensions } from '@xdevplatform/chat-xdk';
    import { readFile } from 'fs/promises';

    const plaintext = await readFile('photo.jpg');
    const mime = detectMimeType(plaintext);
    const dims = detectImageDimensions(plaintext);
    const width = dims?.width ?? 0;
    const height = dims?.height ?? 0;

    const encryptedBlob = chat.encryptStream(plaintext, rawConvKey);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use chat_xdk_core::{detect_image_dimensions, detect_mime_type};

    let plaintext = std::fs::read("photo.jpg")?;
    let _mime = detect_mime_type(&plaintext);
    let dims = detect_image_dimensions(&plaintext);
    let (width, height) = dims.map(|d| (d.width as i64, d.height as i64)).unwrap_or((0, 0));
    // conv_key: &XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
    let encrypted_blob = chat.encrypt_stream(&plaintext, &conv_key)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    plaintext, err := os.ReadFile("photo.jpg")
    mime, _ := chatxdk.DetectMimeType(plaintext)
    dims, _ := chatxdk.DetectImageDimensions(plaintext)
    _ = mime
    encrypted, err := chat.EncryptStream(plaintext, rawConvKey)
    _ = dims
    _ = encrypted
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    using ChatXdk;

    byte[] plaintext = await File.ReadAllBytesAsync("photo.jpg");
    string? mime = ChatXdkUtilities.DetectMimeType(plaintext);
    var dims = ChatXdkUtilities.DetectImageDimensions(plaintext);
    int width = (int)(dims?.Width ?? 0);
    int height = (int)(dims?.Height ?? 0);
    byte[] encryptedBlob = chat.EncryptStream(plaintext, rawConvKey);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.x.chatxdk.ChatXdkUtilities;
    import com.x.chatxdk.Types.ImageDimensions;

    byte[] plaintext = Files.readAllBytes(Path.of("photo.jpg"));
    String mime = ChatXdkUtilities.detectMimeType(plaintext);
    ImageDimensions dims = ChatXdkUtilities.detectImageDimensions(plaintext);
    int width = dims != null ? (int) dims.width : 0;
    int height = dims != null ? (int) dims.height : 0;
    byte[] encryptedBlob = chat.encryptStream(plaintext, rawConvKey);
    ```
  </Tab>
</Tabs>

`encrypt_stream` / `decrypt_stream` process the whole payload in memory. For large files, `stream_encryptor()` / `stream_decryptor()` return incremental objects (`StreamEncryptor` / `StreamDecryptor`): feed chunks with `push`, then call `finish` once; `finish` errors if the stream was truncated.

***

## Upload

| Step       | Method | Path                                 |
| :--------- | :----- | :----------------------------------- |
| Initialize | `POST` | `/2/chat/media/upload/initialize`    |
| Append     | `POST` | `/2/chat/media/upload/{id}/append`   |
| Finalize   | `POST` | `/2/chat/media/upload/{id}/finalize` |

Use the request bodies on the OpenAPI pages under **API reference → Media**. Prefer **encrypted** blob size where size is required. Finalize yields **`media_hash_key`** for attachments and download. Retry transient `5xx` with backoff. Python/TypeScript may use the XDK when media helpers exist; otherwise POST with a Bearer token in any language.

***

## Send with an attachment

Encrypt with a media attachment, then POST the send-message body (same field mapping as [Getting Started](/xchat/getting-started#5-send-a-message)). The SDK generates the `message_id` and returns it on the payload. Send that value, and reuse the same payload on retries so an id is never minted twice.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from xdk.chat.models import SendMessageRequest

    # chat has keys loaded and set_identity called (see Getting Started)
    payload = chat.encrypt_message(
        conversation_id,
        caption or "",
        conversation_key=raw_conv_key,
        conversation_key_version=conversation_key_version,
        attachments=[{
            "attachment_type": "media",
            "media_hash_key": media_hash_key,
            "width": width,
            "height": height,
            "filesize_bytes": len(plaintext),
            "filename": "photo.jpg",
        }],
    )
    client.chat.send_message(
        conversation_id.replace(":", "-"),
        SendMessageRequest(
            message_id=payload.message_id,  # generated by the SDK
            encoded_message_create_event=payload.encrypted_content,
            encoded_message_event_signature=payload.encoded_event_signature,
        ),
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    // chat has keys loaded and setIdentity called (see Getting Started)
    const payload = chat.encryptMessage({
      conversationId,
      text: caption || '',
      conversationKey: rawConvKey,
      conversationKeyVersion,
      attachments: [{
        attachment_type: 'media',
        media_hash_key: mediaHashKey,
        width,
        height,
        filesize_bytes: plaintext.byteLength,
        filename: 'photo.jpg',
      }],
    });
    await client.chat.sendMessage(conversationId.replace(/:/g, '-'), {
      message_id: payload.messageId, // generated by the SDK
      encoded_message_create_event: payload.encryptedContent,
      encoded_message_event_signature: payload.encodedEventSignature,
    });
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use chat_xdk_core::{AttachmentDescriptor, EncryptMessageParams};

    // chat has keys loaded and set_identity called (see Getting Started)
    let mut params = EncryptMessageParams::new(&conversation_id, caption)
        .with_conversation_key(conv_key.to_bytes(), &conversation_key_version);
    params.attachments = Some(vec![AttachmentDescriptor::Media {
        media_hash_key: media_hash_key.clone(),
        width,
        height,
        filesize_bytes: plaintext.len() as i64,
        filename: "photo.jpg".into(),
        media_type: None,
        duration_millis: None,
    }]);
    let payload = chat.encrypt_message(params)?;
    let body = serde_json::json!({
        "message_id": payload.message_id, // generated by the SDK
        "encoded_message_create_event": payload.encrypted_content,
        "encoded_message_event_signature": payload.encoded_event_signature,
    });
    let path_id = conversation_id.replace(':', "-");
    http.post(format!("https://api.x.com/2/chat/conversations/{path_id}/messages"))
        .header("Authorization", &auth)
        .json(&body)
        .send()?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    // chat has keys loaded and SetIdentity called (see Getting Started)
    payload, err := chat.EncryptMessage(chatxdk.EncryptMessageParams{
        ConversationID:         conversationID,
        Text:                   caption,
        ConversationKey:        rawConvKey,
        ConversationKeyVersion: conversationKeyVersion,
        Attachments: []chatxdk.AttachmentDescriptor{{
            AttachmentType: "media",
            MediaHashKey:   mediaHashKey,
            Width:          width,
            Height:         height,
            FilesizeBytes:  int64(len(plaintext)),
            Filename:       "photo.jpg",
        }},
    })
    // POST payload.MessageID (generated by the SDK), payload.EncryptedContent,
    // and payload.EncodedEventSignature to /2/chat/conversations/{id}/messages
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    // chat has keys loaded and SetIdentity called (see Getting Started)
    var payload = chat.EncryptMessage(new EncryptMessageParams(conversationId, caption ?? "")
    {
        ConversationKey = rawConvKey,
        ConversationKeyVersion = conversationKeyVersion,
        Attachments = new[]
        {
            AttachmentDescriptor.Media(mediaHashKey, width, height, plaintext.Length, "photo.jpg"),
        },
    });
    // POST payload.MessageId (generated by the SDK), payload.EncryptedContent,
    // and payload.EncodedEventSignature as for text messages
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    // chat has keys loaded and setIdentity called (see Getting Started)
    EncryptMessageParams params =
        new EncryptMessageParams(conversationId, caption != null ? caption : "");
    params.conversationKey = rawConvKey;
    params.conversationKeyVersion = conversationKeyVersion;
    params.attachments = List.of(AttachmentDescriptor.media(
        mediaHashKey, width, height, plaintext.length, "photo.jpg", null, null));
    SendPayload payload = chat.encryptMessage(params);
    // POST payload.messageId (generated by the SDK), payload.encryptedContent,
    // and payload.encodedEventSignature to /2/chat/conversations/{id}/messages
    ```
  </Tab>
</Tabs>

The conversation key pair can be omitted entirely: with `set_cache_keys(true)` enabled, `encrypt_message` resolves the key and version from the conversation's latest verified key change (see [Getting Started](/xchat/getting-started)).

***

## Download and decrypt

Path: [`GET /2/chat/media/{conversation_id}/{media_hash_key}`](/x-api/chat/download-chat-media). Response body is ciphertext. On inbound messages, read `media_hash_key` from decrypted attachments / `media_hashes`.

**Pick the key by the event's key version.** Each decrypted message event carries the `keyVersion` (JS; `key_version` in the other bindings) its content was encrypted under. Decrypt an attachment with the conversation key for **that** version (`conversationKeys.keys[event.keyVersion]`), not the latest. After a key rotation (for example a member add), the latest key cannot decrypt media attached to older messages.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    keys = result["conversation_keys"]["keys"]
    key_for_media = keys[event["key_version"]]   # not the latest version
    plaintext = chat.decrypt_stream(encrypted_blob, key_for_media)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const keys = result.conversationKeys.keys;
    const keyForMedia = keys[event.keyVersion]; // not the latest version
    const plaintext = chat.decryptStream(encryptedBlob, keyForMedia);
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import requests
    from chat_xdk import detect_mime_type

    api_id = conversation_id.replace(":", "-")
    url = f"https://api.x.com/2/chat/media/{api_id}/{media_hash_key}"
    r = requests.get(url, headers={"Authorization": f"Bearer {access_token}"})
    r.raise_for_status()

    plaintext = chat.decrypt_stream(r.content, raw_conv_key)
    mime = detect_mime_type(plaintext) or "application/octet-stream"
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { detectMimeType } from '@xdevplatform/chat-xdk';

    const apiId = conversationId.replace(/:/g, '-');
    const res = await fetch(
      `https://api.x.com/2/chat/media/${apiId}/${mediaHashKey}`,
      { headers: { Authorization: `Bearer ${accessToken}` } },
    );
    const encryptedBlob = new Uint8Array(await res.arrayBuffer());
    const plaintext = chat.decryptStream(encryptedBlob, rawConvKey);
    const mime = detectMimeType(plaintext) ?? 'application/octet-stream';
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let api_id = conversation_id.replace(':', "-");
    let encrypted_blob = http
        .get(format!("https://api.x.com/2/chat/media/{api_id}/{media_hash_key}"))
        .header("Authorization", &auth)
        .send()?
        .bytes()?;
    // conv_key: &XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
    let plaintext = chat.decrypt_stream(&encrypted_blob, &conv_key)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    url := fmt.Sprintf("https://api.x.com/2/chat/media/%s/%s",
        strings.ReplaceAll(conversationID, ":", "-"), mediaHashKey)
    req, _ := http.NewRequest(http.MethodGet, url, nil)
    req.Header.Set("Authorization", "Bearer "+accessToken)
    resp, err := http.DefaultClient.Do(req)
    // read body into []byte → chat.DecryptStream(encryptedBlob, rawConvKey)
    _ = resp
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    var apiId = conversationId.Replace(':', '-');
    byte[] encryptedBlob = await http.GetByteArrayAsync(
        $"https://api.x.com/2/chat/media/{apiId}/{mediaHashKey}");
    byte[] plaintext = chat.DecryptStream(encryptedBlob, rawConvKey);
    string? mime = ChatXdkUtilities.DetectMimeType(plaintext);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String apiId = conversationId.replace(':', '-');
    HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create("https://api.x.com/2/chat/media/" + apiId + "/" + mediaHashKey))
        .header("Authorization", "Bearer " + accessToken)
        .GET()
        .build();
    byte[] encryptedBlob = http.send(req, HttpResponse.BodyHandlers.ofByteArray()).body();
    byte[] plaintext = chat.decryptStream(encryptedBlob, rawConvKey);
    String mime = ChatXdkUtilities.detectMimeType(plaintext);
    ```
  </Tab>
</Tabs>

***

## Tips

* Use the same **conversation key version** as when the media was encrypted
* Do not log plaintext media or raw keys
* Detect MIME **after** decrypt
* Web clients: encrypt/decrypt on the client when possible; keep OAuth tokens on your server

Full request and response schemas for each media route are under **API reference → Media** in the sidebar (initialize upload, append chunk, finalize upload, and download media).


# Get new X Chat messages as they arrive
Source: https://docs.x.com/xchat/real-time-events

Listen for new X Chat messages and events in real time using webhooks or a stream, then decrypt them with the Chat XDK.

X delivers **`chat.received`**, **`chat.sent`**, and related X Chat activity with **ciphertext** in the payload. Decrypt with the [Chat XDK](/xchat/xchat-xdk).

| Layer              | Role                                                                                                                                |
| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| **X Activity API** | `GET /2/activity/stream`; `POST` / `GET` / `PUT` / `DELETE` `/2/activity/subscriptions` (see OpenAPI security per operation)        |
| **Webhooks**       | Optional `POST` / `GET` `/2/webhooks` and `PUT` / `DELETE` `/2/webhooks/{webhook_id}` routes if you terminate on your own HTTPS URL |
| **Chat XDK**       | `decrypt_event` / `decrypt_events`, with the `set_signing_keys` / `set_cache_keys` session stores                                   |

Private X Chat event types need authorization for the user you monitor. Encrypted X Chat file attachments use **`media_hash_key`** and X Chat media download, not Post API `expansions=attachments.media_keys` / `media.fields=variants`.

***

## Event types

| Event                    | When                                         |
| :----------------------- | :------------------------------------------- |
| `chat.received`          | Subscribed user receives an encrypted DM     |
| `chat.sent`              | Subscribed user sends an encrypted DM        |
| `chat.conversation_join` | Subscribed user joins a group (when offered) |

***

## 1. Choose delivery

**Activity stream (often simplest for bots):** `GET /2/activity/stream` with an app Bearer token (optional `backfill_minutes`, `start_time`, `end_time` per OpenAPI). Filter client-side for `chat.received` / `chat.sent`.

**Activity subscriptions:** manage durable subscriptions with:

* `POST /2/activity/subscriptions`: create
* `GET /2/activity/subscriptions`: list (paginated)
* `PUT /2/activity/subscriptions/{subscription_id}`: update
* `DELETE /2/activity/subscriptions/{subscription_id}` or `DELETE /2/activity/subscriptions?ids=`: delete

Request bodies and required scopes are defined in the OpenAPI operation for each route. Creating an X Activity API (XAA) subscription requires **user-context authorization** (OAuth 2.0 user context with the relevant scopes, such as `dm.read` for chat events) for the user whose activity you monitor.

**Webhooks:** if you terminate events on your HTTPS endpoint, register a webhook with `POST /2/webhooks`, pass CRC challenges, then create your activity subscriptions with `POST /2/activity/subscriptions`, referencing your `webhook_id` (see Webhooks and Activity operations in OpenAPI). Python/TypeScript XDK may expose helpers for webhooks and activity when your SDK version includes them.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from xdk import Client

    # Stream (app token); exact helper names depend on your XDK version
    stream_client = Client(bearer_token="YOUR_BEARER_TOKEN")
    # for event in stream_client.activity.stream():
    #     handle_payload(event)  # see "Decrypt with the Chat XDK" below

    # Or create a subscription; requires user-context auth for the monitored user
    client = Client(access_token="YOUR_OAUTH2_USER_TOKEN")
    client.activity.create_subscription({
        "event_type": "chat.received",
        "filter": {"user_id": "USER_ID_TO_MONITOR"},
    })
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { Client } from '@xdevplatform/xdk';

    // Creating a subscription requires user-context auth for the monitored user
    const client = new Client({ accessToken: 'YOUR_OAUTH2_USER_TOKEN' });
    await client.activity.createSubscription({
      event_type: 'chat.received',
      filter: { user_id: 'USER_ID_TO_MONITOR' },
    });
    // Stream: client.activity.stream() when available in your SDK version
    ```
  </Tab>
</Tabs>

Subscribe to `chat.sent` as well if you need outbound copies. Other languages: call the same `/2/activity/*` HTTPS routes directly (user-context token to create subscriptions, app Bearer token for the stream).

***

## 2. CRC (webhooks only)

If you use webhooks, respond to Challenge-Response Checks (GET `crc_token`) with HMAC-SHA256 of the token using your consumer secret, in the JSON shape your webhook product expects (typically `sha256=<base64>`).

***

## 3. Decrypt with the Chat XDK

Live fields: **`payload.encoded_event`**, optional **`payload.conversation_key_change_event`**. Deduplicate deliveries on **`event_uuid`**; deduplicate messages on the **`message_id`** carried in the decrypted event. It is part of the signed content, while sequence ids are backend-assigned, unsigned metadata.

The snippets below use the two **optional** session stores for the shortest handler: `set_signing_keys` holds the participants' public keys (fetched once from the [public-keys endpoint](/x-api/chat/get-user-public-keys)), and `set_cache_keys(true)` keeps each conversation's verified key, so `decrypt_event` needs only the event. When a payload carries `conversation_key_change_event`, run it through `decrypt_events` first: that verifies the key change and, with caching on, retains its key for the `decrypt_event` call. Prefer no instance state? Pass the keys per call instead; see the note at the end of this section.

JavaScript uses camelCase event types (`message`); other bindings use `"Message"` and snake\_case fields.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # chat has keys loaded and set_identity called (see Getting Started)
    chat.set_cache_keys(True)
    chat.set_signing_keys(participant_signing_keys)  # all participants, from the public-key routes

    data = body.get("data") or {}
    if data.get("event_type") in ("chat.received", "chat.sent"):
        p = data.get("payload") or {}
        if p.get("conversation_key_change_event"):
            # Verify the key change and retain its key in the cache
            chat.decrypt_events([p["conversation_key_change_event"]])
        ev = chat.decrypt_event(p["encoded_event"])
        if ev["type"] == "Message":
            print(ev["sender_id"], ev["content"]["text"])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    // chat has keys loaded and setIdentity called (see Getting Started)
    chat.setCacheKeys(true);
    chat.setSigningKeys(participantSigningKeys); // all participants, from the public-key routes

    const data = body?.data ?? {};
    if (data.event_type === 'chat.received' || data.event_type === 'chat.sent') {
      const p = data.payload ?? {};
      if (p.conversation_key_change_event) {
        // Verify the key change and retain its key in the cache
        chat.decryptEvents([p.conversation_key_change_event]);
      }
      const ev = chat.decryptEvent(p.encoded_event);
      if (ev.type === 'message') {
        console.log(ev.senderId, ev.content.text);
      }
    }
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // chat has keys loaded and set_identity called (see Getting Started)
    chat.set_cache_keys(true);
    chat.set_signing_keys(participant_signing_keys); // all participants

    if let Some(kc) = key_change.as_deref() {
        // Verify the key change and retain its key in the cache
        let _ = chat.decrypt_events(&[kc], &[]);
    }
    // Decrypt with the cached conversation key; verify against the stored signing keys
    let event = chat.decrypt_event(&encoded_event, &Default::default(), &[])?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    // chat has keys loaded and SetIdentity called (see Getting Started)
    chat.SetCacheKeys(true)
    _ = chat.SetSigningKeys(participantSigningKeys) // all participants

    if keyChange != "" {
        // Verify the key change and retain its key in the cache
        _, _ = chat.DecryptEvents([]string{keyChange}, nil)
    }
    // Decrypt with the cached conversation key; verify against the stored signing keys
    event, err := chat.DecryptEvent(encodedEvent, nil, nil)
    if err == nil && event.Type == "Message" {
        fmt.Println(event.AsMessage().Text())
    }
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    // chat has keys loaded and SetIdentity called (see Getting Started)
    chat.SetCacheKeys(true);
    chat.SetSigningKeys(participantSigningKeys); // all participants

    if (!string.IsNullOrEmpty(keyChangeB64))
    {
        // Verify the key change and retain its key in the cache
        chat.DecryptEvents(new[] { keyChangeB64 });
    }
    // Decrypt with the cached conversation key; verify against the stored signing keys
    var evt = chat.DecryptEvent(encodedEvent);
    if (evt.GetProperty("type").GetString() == "Message")
        Console.WriteLine(evt.GetProperty("content").GetProperty("text").GetString());
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    // chat has keys loaded and setIdentity called (see Getting Started)
    chat.setCacheKeys(true);
    chat.setSigningKeys(participantSigningKeys); // all participants

    if (keyChangeB64 != null && !keyChangeB64.isEmpty()) {
        // Verify the key change and retain its key in the cache
        chat.decryptEvents(List.of(keyChangeB64), null);
    }
    // Decrypt with the cached conversation key; verify against the stored signing keys
    JsonNode evt = chat.decryptEvent(encodedEvent, (Map<String, byte[]>) null, null);
    if ("Message".equals(evt.path("type").asText())) {
        System.out.println(evt.path("content").path("text").asText());
    }
    ```
  </Tab>
</Tabs>

To keep the key maps in your own hands instead, `extract_conversation_keys` decrypts the keys from `conversation_key_change_event` and `decrypt_event` accepts them (and the sender's signing keys) as explicit arguments; an explicit non-empty argument always wins over the stores.

History: [`GET /2/chat/conversations/{id}/events`](/x-api/chat/get-chat-conversation-events) + **`decrypt_events`**; see [Getting Started](/xchat/getting-started#6-receive-and-decrypt).

***

## Payload shape (live)

```json title="chat.received" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "event_type": "chat.received",
    "event_uuid": "0f52b591-4b7e-4f13-92cd-30e6b2a3f18a",
    "payload": {
      "conversation_id": "1215441834412953600-1843439638876491776",
      "sender_id": "1843439638876491776",
      "encoded_event": "BASE64_ENCODED_MESSAGE_EVENT",
      "conversation_key_version": "1782945126642",
      "conversation_key_change_event": "BASE64_ENCODED_KEY_CHANGE_EVENT"
    }
  }
}
```

***

## Practices

* Verify webhook signatures per platform requirements
* Set the session stores once: `set_signing_keys` for all participants, `set_cache_keys(true)` for conversation keys
* Apply key-change blobs (via `decrypt_events`) before decrypting dependent messages
* Deduplicate deliveries on `event_uuid` and messages on the signed `message_id`


# Fix common X Chat problems
Source: https://docs.x.com/xchat/troubleshooting

Solutions for the most common X Chat issues: key setup, backup recovery, messages that won't decrypt, and send errors.

This page covers problems that are **specific to X Chat encryption and the Chat XDK**: keys, secure key backup, decrypt/verify, and building encrypted send payloads.

For webhooks, OAuth, HTTP status codes, and rate limits, use the general [X API](/x-api/introduction) and [authentication](/fundamentals/authentication/overview) documentation.

***

## Keys and secure key backup

### Unlock fails (invalid passcode)

* Confirm the passcode matches the one used with `setup`
* Wait between attempts; realms rate-limit wrong guesses and can lock recovery after too many failures

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    try:
        chat.unlock(passcode)
    except ValueError as e:
        print(e)  # may mention InvalidPin or guesses remaining
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    try {
      await chat.unlock(passcode);
    } catch (e) {
      console.error((e as Error).message);
    }
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    chat.unlock(passcode_bytes).await?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    if err := chat.Unlock(passcode, juiceboxConfigJSON); err != nil {
        log.Println(err)
    }
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    try { chat.Unlock(passcode, juiceboxConfigJson); }
    catch (Exception e) { Console.WriteLine(e.Message); }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    try { chat.unlock(passcode, juiceboxConfigJson); }
    catch (Exception e) { System.out.println(e.getMessage()); }
    ```
  </Tab>
</Tabs>

### Encrypt or decrypt fails because keys or identity are not set

Load private keys first, then set the **session identity**: your user id plus the `public_key_version` from your record on X. The `encrypt_*` and `prepare_*` methods sign with it; calling them with no session identity (and no explicit per-call override) is an error.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    chat.unlock(passcode)  # or: chat.import_keys(blob)
    chat.set_identity(my_user_id, signing_key_version)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await chat.unlock(passcode);
    chat.setIdentity(myUserId, signingKeyVersion);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    chat.import_keys(&blob)?;
    chat.set_identity(&my_user_id, &signing_key_version);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    blob, _ := chatxdk.Base64ToBytes(privateKeysB64)
    _ = chat.ImportKeys(blob)
    _ = chat.SetIdentity(myUserID, signingKeyVersion)
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    chat.ImportKeys(blobBytes);
    chat.SetIdentity(myUserId, signingKeyVersion);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    chat.importKeys(blobBytes);
    chat.setIdentity(myUserId, signingKeyVersion);
    ```
  </Tab>
</Tabs>

### Your local public key never matches the account's registered keys

Clients often need to answer *"is the key on this device one of the keys registered to this account?"*, after a restore or import, to adopt the right `public_key_version`, or to decide whether onboarding already happened. Comparing the Chat XDK's `get_public_keys` output against the API's `public_key` field **as strings always fails**, even for the same key, because the two use different encodings:

* The **API** stores and returns the key exactly as registration uploaded it: the DER (SPKI) encoding, which is the raw key behind a fixed algorithm-identifier prefix
* The **Chat XDK**'s `get_public_keys` returns the raw key alone, without that prefix

Same key, two spellings. To compare, base64-decode both and check that the API bytes **end with** the SDK bytes (identical bytes also match, in case both sides ever hold the same encoding):

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import base64

    def same_key(local_b64: str, server_b64: str) -> bool:
        local = base64.b64decode(local_b64)    # chat.get_public_keys()["identity"]
        server = base64.b64decode(server_b64)  # API row's "public_key"
        return local == server or (len(server) > len(local) and server.endswith(local))
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const sameKey = (localB64: string, serverB64: string): boolean => {
      const local = Buffer.from(localB64, 'base64');   // chat.getPublicKeys().identity
      const server = Buffer.from(serverB64, 'base64'); // API row's public_key
      return local.equals(server) ||
        (server.length > local.length && server.subarray(server.length - local.length).equals(local));
    };
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    fn same_key(local: &[u8], server: &[u8]) -> bool {
        local == server || (server.len() > local.len() && server.ends_with(local))
    }
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    func sameKey(local, server []byte) bool {
        return bytes.Equal(local, server) ||
            (len(server) > len(local) && bytes.HasSuffix(server, local))
    }
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    static bool SameKey(byte[] local, byte[] server) =>
        local.SequenceEqual(server) ||
        (server.Length > local.Length &&
         server.AsSpan(server.Length - local.Length).SequenceEqual(local));
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    static boolean sameKey(byte[] local, byte[] server) {
        if (Arrays.equals(local, server)) return true;
        if (server.length <= local.length) return false;
        byte[] tail = Arrays.copyOfRange(server, server.length - local.length, server.length);
        return Arrays.equals(tail, local);
    }
    ```
  </Tab>
</Tabs>

Once matched, adopt that row's `public_key_version` for `set_identity`. When comparing versions (for example to pick the newest key), compare **numerically**: versions are millisecond timestamps of varying string length, so lexicographic comparison picks the wrong one.

### Missing conversation key for a message

An error like `Message encrypted with key version '…' but no matching key found` means you do not have the **raw** key for that message's `conversation_key_version`.

1. Decrypt key material from `conversation_key_change_event` (live events) or `meta.conversation_key_events` (history) with `extract_conversation_keys`, **or** include those blobs in `decrypt_events`; with `set_cache_keys(true)` enabled, `decrypt_events` also retains each conversation's latest verified key so later `decrypt_event` and `encrypt_*` calls can omit it
2. Confirm conversation keys were added for that version and you are still a participant (see [Getting Started](/xchat/getting-started#4-set-up-conversation-keys))

### Peer has no public keys

They may not have finished onboarding. After they register, load `public_key`, `signing_public_key`, `identity_public_key_signature`, and `public_key_version` from **API reference → Encryption keys**.

***

## Decryption and signatures

### Decrypt fails

* Stale or wrong **raw** conversation key, or wrong key version
* Incomplete `encoded_event` string
* Event type is not an encrypted message you can treat as decryptable content

### Signature does not verify

Verification is **fail-closed by default** (`reject_unverified = true`): the SDK already rejects unverified signed events, so a failure here means the verification inputs are wrong, not that you need to turn checking on. Common causes:

* Missing or incomplete signing-key entry for the **sender** (all fields required by the Chat XDK; see the [Chat XDK](/xchat/xchat-xdk) reference)
* No signing keys passed on the call and none stored via `set_signing_keys`
* The sender rotated versions: re-fetch their public keys
* A key version below the accepted floor never verifies
* On a **group key-change event**, the signer has since left the group, so their keys are no longer served; see [Key changes from departed members](/xchat/groups#key-changes-from-departed-members)

The `set_reject_unverified` setter exists to opt **out** of this default (`false`, not recommended). If you disabled it earlier, restore the fail-closed default:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    chat.set_reject_unverified(True)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    chat.setRejectUnverified(true);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    chat.set_reject_unverified(true);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    chat.SetRejectUnverified(true)
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    chat.SetRejectUnverified(true);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    chat.setRejectUnverified(true);
    ```
  </Tab>
</Tabs>

### A reply carries `reply_preview_validation: "Invalid"`

Decrypted replies may carry `reply_preview_validation` (`"Valid"` / `"Invalid"`; JavaScript uses `'valid'` / `'invalid'`). `Invalid` means the quoted preview inside the message does not match the signed original event it embeds. Treat the quote as untrusted and render the quoted content only from the validated original. The message itself is verified separately and is still authentic; nothing throws for an invalid preview.

### Old events permanently fail verification

Errors like `signature missing or no matching signing key` or an ECDSA mismatch on **old** events are permanent. Signatures are immutable and verified by rebuilding the signed payload from the event itself, so an event that was signed over different bytes (or never signed) fails on every future load. No retry, key refresh, or API call can heal it. Treat these events as tombstones, not retryable errors. Rotating the conversation key starts a clean, verifiable history from that point forward; new messages are unaffected.

***

## Building the send payload

These mistakes are specific to X Chat encryption (not general HTTP errors):

| Issue                  | Fix                                                                                                                                                                                                              |
| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Wrong key bytes        | Pass the **raw** conversation key bytes into the Chat XDK, not the encrypted key string from the API                                                                                                             |
| Wrong JSON field names | Map `encrypted_content` → `encoded_message_create_event` and `encoded_event_signature` → `encoded_message_event_signature`                                                                                       |
| Wrong message id       | Send the `message_id` from the returned payload: the SDK generates it and embeds it in the signed event, so any other value fails. On retries, reuse the same encrypted payload so the id is never minted twice  |
| Version mismatch       | Align `conversation_key_version` with the key you use; align the signing key version passed to `set_identity` with your public-key record                                                                        |
| Path id form           | URL paths still need the hyphenated conversation id (`:` → `-`), but for signing the SDK accepts any form: `A:B`, `A-B` (either order), or the bare recipient user id; all canonicalize to the same signed bytes |

### API returns 400 for a state-changing call

Every state-changing chat call (adding or rotating conversation keys, creating a group, adding members) requires **`action_signatures`** in the request body, validated at the API boundary. A missing or malformed entry (each needs `message_id`, `encoded_message_event_detail`, and a `message_event_signature` with `signature`, `public_key_version`, and `signature_version`) returns an HTTP 400 problem-details response immediately. Use the SDK prepare methods (`prepare_conversation_key_change`, `prepare_group_create`, `prepare_group_members_change`) and send **all** returned signatures; group create and member adds return two.

***

## Media encrypt and decrypt

* Use the **same** conversation key (and version) as the message that references the attachment
* Treat download responses as **ciphertext** until you run `decrypt_stream`
* Infer MIME type **after** decrypt; the download `Content-Type` is often not the real image type

Details: [Media](/xchat/media).

***

## Safe debugging

When investigating crypto failures:

* Log conversation ids, event ids, and key **versions** only
* Do **not** log plaintext, passcodes, private keys, or full key blobs
* Confirm the signing-key version passed to `set_identity` matches the `public_key_version` on your public-key record
* For incomplete history, page **all** event pages so key-change metadata is not skipped before decrypting


# Chat XDK: the encryption toolkit for X Chat
Source: https://docs.x.com/xchat/xchat-xdk

Meet the Chat XDK, the library that handles keys, encryption, decryption, and signing for you, with references for every supported language.

The **Chat XDK** handles key management, encryption, decryption, and signing for X Chat. It does **not** call the X HTTP API: pair it with the [Python](/xdks/python/overview) or [TypeScript](/xdks/typescript/overview) **XDK**, or with HTTPS and a user access token.

App walkthrough: [Getting Started](/xchat/getting-started). Sample bots: [chat-xdk/examples](https://github.com/xdevplatform/chat-xdk/tree/main/examples).

### Install

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install chatxdk
    ```

    The PyPI package is `chatxdk`; import it as `chat_xdk`. Requires Python 3.10+.
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install @xdevplatform/chat-xdk
    npm install juicebox-sdk   # optional peer dependency; required for setup()/unlock() secure key backup
    ```

    The compiled WASM engine ships inside the package; there is no build step. Requires Node.js 18+.
  </Tab>

  <Tab title="Rust">
    ```toml theme={null}
    [dependencies]
    # chat-xdk-core is not yet on crates.io; use the git dependency.
    # It exports both ChatCore and the async secure-key-backup Chat type.
    chat-xdk-core = { git = "https://github.com/xdevplatform/chat-xdk" }  # pin a release tag in production, e.g. tag = "vX.Y.Z"

    # Required until thrift 0.24 is released on crates.io
    [patch.crates-io]
    thrift = { git = "https://github.com/apache/thrift.git", rev = "deb36fa409849de45973b04ffc3ce49d277ca90a" }
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/xdevplatform/chat-xdk/go/chatxdk
    ```

    Precompiled static libraries are included (macOS arm64/amd64, Linux amd64 glibc/musl): you need a C compiler but not Rust. Requires Go 1.21+.
  </Tab>

  <Tab title="C#">
    ```bash theme={null}
    dotnet add package XDevPlatform.ChatXdk
    ```

    The package is self-contained: native libraries for macOS (arm64, x64), Linux (x64), and Windows (x64) ship inside it. Requires .NET 8+.
  </Tab>

  <Tab title="Java">
    ```xml theme={null}
    <dependency>
      <groupId>com.x</groupId>
      <artifactId>chatxdk</artifactId>
      <!-- Use the latest version from https://central.sonatype.com/artifact/com.x/chatxdk -->
      <version>x.y.z</version>
    </dependency>
    ```

    Available on Maven Central. The jar bundles the native library for macOS (arm64, x64), Linux (x64), and Windows (x64); no `jna.library.path` setup is needed. Import from `com.x.chatxdk`. Requires JDK 17+.
  </Tab>
</Tabs>

***

## Quick start

Load keys, set your identity once, decrypt a backlog, decrypt one live event, encrypt a message. Wire the send body to [`POST /2/chat/conversations/{id}/messages`](/x-api/chat/send-chat-message) as in [Getting Started](/xchat/getting-started).

The snippets use the two **optional** session stores for the shortest call forms: `set_signing_keys` holds the other participants' public keys (fetched from the [public-keys endpoint](/x-api/chat/get-user-public-keys)) so decrypt calls can verify senders without a per-call argument, and `set_cache_keys(true)` lets the SDK remember each conversation's verified key so encrypt calls need only the conversation id and text. Skip either and pass the same values per call instead; both styles verify identically. See [Decrypt](#decrypt).

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from chat_xdk import Chat

    chat = Chat(juicebox_config_json)  # or Chat() + import_keys(blob, version)
    chat.unlock("YOUR_PASSCODE")

    # Session defaults: identity for signing, stored signing keys for
    # verification, opt-in cache for conversation keys
    chat.set_identity(my_user_id, signing_key_version)
    chat.set_signing_keys(signing_keys)  # all participants
    chat.set_cache_keys(True)

    # Batch-decrypt the backlog; senders verify against the stored keys
    result = chat.decrypt_events(raw_events)
    for dm in result["messages"]:
        ev = dm["event"]
        if ev["type"] == "Message":
            print(ev["sender_id"], ev["content"]["text"])

    # Decrypt one live event with the cached conversation key
    event = chat.decrypt_event(one_event_b64)

    # Encrypt and sign as the session identity, under the cached key
    payload = chat.encrypt_message(event["conversation_id"], "Hi!")
    message_id = payload.message_id  # SDK-generated; send as message_id
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { createChat } from '@xdevplatform/chat-xdk';

    const chat = await createChat({
      juiceboxConfig: juiceboxConfigJson,
      getAuthToken: async (realmId) => getRealmToken(realmId),
    });
    await chat.unlock('YOUR_PASSCODE');

    // Session defaults: identity for signing, stored signing keys for
    // verification, opt-in cache for conversation keys
    chat.setIdentity(myUserId, signingKeyVersion);
    chat.setSigningKeys(signingKeys); // all participants
    chat.setCacheKeys(true);

    // Batch-decrypt the backlog; senders verify against the stored keys
    const result = chat.decryptEvents(rawEvents);
    for (const dm of result.messages) {
      if (dm.event.type === 'message') {
        console.log(dm.event.senderId, dm.event.content?.text);
      }
    }

    // Decrypt one live event with the cached conversation key
    const event = chat.decryptEvent(oneEventB64);

    // Encrypt and sign as the session identity, under the cached key
    const payload = chat.encryptMessage({ conversationId: event.conversationId!, text: 'Hi!' });
    const messageId = payload.messageId; // SDK-generated; send as message_id
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // chat_xdk_core::Chat + unlock(b"…").await, or ChatCore + import_keys_with_version

    // Session defaults: identity for signing, stored signing keys for
    // verification, opt-in cache for conversation keys
    chat.set_identity(my_user_id, signing_key_version);
    chat.set_signing_keys(signing_keys); // all participants
    chat.set_cache_keys(true);

    // Batch-decrypt the backlog; senders verify against the stored keys
    let result = chat.decrypt_events(&raw_events, &[]);
    for dm in &result.messages {
        if let Event::Message(msg) = &dm.event {
            println!("{}: {}", msg.meta.sender_id.as_deref().unwrap_or("?"), msg.text().unwrap_or(""));
        }
    }

    // Decrypt one live event with the cached conversation key
    let event = chat.decrypt_event(one_event_b64, &Default::default(), &[])?;

    // Encrypt and sign as the session identity, under the cached key
    let payload = chat.encrypt_message(EncryptMessageParams::new(conversation_id, "Hi!"))?;
    let message_id = payload.message_id; // SDK-generated; send as message_id
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    chat := chatxdk.New()
    defer chat.Close()
    blob, _ := chatxdk.Base64ToBytes(privateKeysB64)
    _ = chat.ImportKeysWithVersion(blob, signingKeyVersion)

    // Session defaults: identity for signing, stored signing keys for
    // verification, opt-in cache for conversation keys
    chat.SetIdentity(myUserID, signingKeyVersion)
    _ = chat.SetSigningKeys(signingKeys) // all participants
    chat.SetCacheKeys(true)

    // Batch-decrypt the backlog; senders verify against the stored keys
    result, err := chat.DecryptEvents(rawEvents, nil)
    for _, dm := range result.Messages {
        if dm.Event.Type == "Message" {
            fmt.Println(dm.Event.AsMessage().Text())
        }
    }

    // Decrypt one live event with the cached conversation key
    event, err := chat.DecryptEvent(oneEventB64, nil, nil)
    msg := event.AsMessage() // nil unless event.Type == "Message"

    // Encrypt and sign as the session identity, under the cached key
    payload, err := chat.EncryptMessage(chatxdk.EncryptMessageParams{
        ConversationID: *msg.ConversationID,
        Text:           "Hi!",
    })
    messageID := payload.MessageID // SDK-generated; send as message_id
    _ = messageID
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    using var chat = new Chat();
    chat.ImportKeys(privateKeyBytes, signingKeyVersion);

    // Session defaults: identity for signing, stored signing keys for
    // verification, opt-in cache for conversation keys
    chat.SetIdentity(myUserId, signingKeyVersion);
    chat.SetSigningKeys(signingKeys); // all participants
    chat.SetCacheKeys(true);

    // Batch-decrypt the backlog; senders verify against the stored keys
    var result = chat.DecryptEvents(rawEvents);
    foreach (var dm in result.Messages)
    {
        if (dm.Event.GetProperty("type").GetString() == "Message")
            Console.WriteLine(dm.Event.GetProperty("content").GetProperty("text").GetString());
    }

    // Decrypt one live event with the cached conversation key
    var evt = chat.DecryptEvent(oneEventB64);
    var conversationId = evt.GetProperty("conversation_id").GetString()!;

    // Encrypt and sign as the session identity, under the cached key
    var payload = chat.EncryptMessage(new EncryptMessageParams(conversationId, "Hi!"));
    var messageId = payload.MessageId; // SDK-generated; send as message_id
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    try (Chat chat = new Chat()) {
        chat.importKeys(privateKeyBytes, signingKeyVersion);

        // Session defaults: identity for signing, stored signing keys for
        // verification, opt-in cache for conversation keys
        chat.setIdentity(myUserId, signingKeyVersion);
        chat.setSigningKeys(signingKeys); // all participants
        chat.setCacheKeys(true);

        // Batch-decrypt the backlog; senders verify against the stored keys
        DecryptEventsResult result = chat.decryptEvents(rawEvents, null);
        for (DecryptedMessage dm : result.messages) {
            if ("Message".equals(dm.event.path("type").asText())) {
                System.out.println(dm.event.path("content").path("text").asText());
            }
        }

        // Decrypt one live event with the cached conversation key
        JsonNode event = chat.decryptEvent(oneEventB64, (Map<String, byte[]>) null, null);
        String conversationId = event.path("conversation_id").asText();

        // Encrypt and sign as the session identity, under the cached key
        SendPayload payload = chat.encryptMessage(new EncryptMessageParams(conversationId, "Hi!"));
        String messageId = payload.messageId; // SDK-generated; send as message_id
    }
    ```
  </Tab>
</Tabs>

***

## Lifecycle and keys

Construct the SDK, store private keys (passcode-protected secure key backup or a local key blob), register **public** keys with the X Chat API, and call **`set_identity(user_id, signing_key_version)`** after unlock or import. It sets the sender and signing-key version every signed action defaults to, so the encrypt and prepare methods work without per-call identity arguments. Call `generate_keypairs` once per device/app identity; post the registration payload to the public-keys endpoint. Use `setup` / `unlock` (and related passcode helpers) for secure key backup on every binding. `export_keys` / `import_keys` (raw key-blob persistence for bots and servers) are available on the **native bindings only**: Python, Go, .NET, JVM, and Rust. The JS/WASM binding does not expose raw key export or import: in a browser any script that reaches the instance could exfiltrate the identity, so JS keeps keys inside secure key backup. A JS server that wants to avoid a backup-realm round-trip per request should reuse one unlocked `Chat` instance across requests, or run a native binding where key blobs are supported.

The SDK also needs the version the X API reports for your registered public key, so key-change entries targeting other versions are skipped. `set_identity` records it together with the user id; `import_keys` accepts it directly as an optional argument (Rust and Go use `import_keys_with_version` / `ImportKeysWithVersion`).

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from chat_xdk import Chat

    # Secure key backup (client)
    chat = Chat(juicebox_config_json)
    chat.setup("YOUR_PASSCODE")          # first time; generates keypairs
    # chat.unlock("YOUR_PASSCODE")        # later sessions
    chat.set_identity(user_id, version)  # version from add-public-key / get-public-keys response
    reg = chat.get_public_keys()     # or registration fields from generate_keypairs

    # Key blob (server / bot)
    chat2 = Chat()
    chat2.import_keys(secret_blob, version)
    chat2.set_identity(user_id, version)
    blob = chat2.export_keys()       # treat as a password
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { createChat } from '@xdevplatform/chat-xdk';

    const chat = await createChat({
      juiceboxConfig: juiceboxConfigJson,
      getAuthToken: async (realmId) => getRealmToken(realmId),
    });
    await chat.setup('YOUR_PASSCODE');
    // await chat.unlock('YOUR_PASSCODE');
    chat.setIdentity(userId, version);
    const publics = chat.getPublicKeys();

    // JS/WASM stores keys only through secure key backup; there is no raw key
    // export/import here. For key-blob persistence, use a native binding.
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // chat_xdk_core::Chat: async secure key backup unlock, or ChatCore + import_keys
    chat.setup(b"YOUR_PASSCODE").await?;
    // chat.unlock(b"YOUR_PASSCODE").await?;
    chat.set_identity(user_id, version);
    let publics = chat.get_public_keys()?;
    let blob = chat.export_keys()?;
    chat.import_keys_with_version(&blob, version)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    chat := chatxdk.New()
    defer chat.Close()

    // Prefer ImportKeys for servers; secure key backup unlock where supported
    keyBlob, _ := chatxdk.Base64ToBytes(privateKeysB64)
    if err := chat.ImportKeysWithVersion(keyBlob, version); err != nil {
        log.Fatal(err)
    }
    chat.SetIdentity(userID, version)
    publics, err := chat.GetPublicKeys()
    blob, err := chat.ExportKeys()
    _ = publics
    _ = blob
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    using var chat = new Chat();
    chat.ImportKeys(privateKeyBytes, version);
    // or secure key backup setup / unlock when config is available
    chat.SetIdentity(userId, version);
    var publics = chat.GetPublicKeys();
    var blob = chat.ExportKeys();
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    try (Chat chat = new Chat()) {
        chat.importKeys(privateKeyBytes, version);
        chat.setIdentity(userId, version);
        var publics = chat.getPublicKeys();
        byte[] blob = chat.exportKeys();
    }
    ```
  </Tab>
</Tabs>

The secure key backup config accepts three shapes: the X API `juicebox_config` object (recommended; passed verbatim), a full `sdk_config` wrapper, or a bare `token_map`.

Optional: signature verification is **on by default** (`reject_unverified = true`); call `set_reject_unverified(false)` to disable it (not recommended); `update_config` if backup realm config changes; `is_unlocked` / `has_identity_key` for UI state. Full field lists live in the [chat-xdk repo](https://github.com/xdevplatform/chat-xdk) stubs.

***

## Conversation keys

Three **prepare** methods each make one call do everything a key change needs: generate a fresh conversation key, encrypt it for every participant (from the public keys you pass), and sign the change. The sender identity and signing-key version come from the session (`set_identity`); set `sender_id` / `signing_key_version` on the params to override. All return the same **`PreparedConversationChange`** shape, ready to POST. Rename SDK field `encrypted_key` to **`encrypted_conversation_key`** in `conversation_participant_keys`, and map the action signatures into the required **`action_signatures`** body field.

| Scenario                                                                                                  | Method                            | Action signatures returned |
| :-------------------------------------------------------------------------------------------------------- | :-------------------------------- | :------------------------- |
| Start a 1:1 (omit the conversation id; the SDK derives it) or rotate any conversation's key (pass the id) | `prepare_conversation_key_change` | 1                          |
| Create a group (id minted by `POST /2/chat/conversations/group/initialize`)                               | `prepare_group_create`            | 2: send both               |
| Add members to a group                                                                                    | `prepare_group_members_change`    | 2: send both               |

Keep the **raw** key bytes for `encrypt_message` and media; never pass the API's encrypted envelope into encrypt.

<Warning>
  **Verify fetched keys before wrapping.** The prepare methods encrypt the fresh conversation key to whatever public keys you pass. Before passing them, call `verify_key_binding(identity, signing, signature)` on each fetched record (its `public_key`, `signing_public_key`, and `identity_public_key_signature` fields from the public-keys API) so a substituted identity key cannot receive the conversation key.
</Warning>

Use `extract_conversation_keys` on key-change event payloads to rebuild `{ keys, latest_version }`. `decrypt_conversation_key` unwraps a single ECIES blob.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # One entry per participant public key, from the public-keys API:
    # participants = [
    #     {"user_id": "1215441834412953600", "public_key": "BASE64_IDENTITY_PUBLIC_KEY", "key_version": "1733889755256"},
    #     {"user_id": "1843439638876491776", "public_key": "BASE64_IDENTITY_PUBLIC_KEY", "key_version": "1766181805686"},
    # ]
    prepared = chat.prepare_conversation_key_change(participants)
    # prepared["conversation_key"]:   raw bytes for encrypt_message
    # prepared["participant_keys"]:   per-user wraps; rename encrypted_key → encrypted_conversation_key on POST
    # prepared["action_signatures"]:  required on the POST body

    extracted = chat.extract_conversation_keys(key_change_blobs)
    keys = extracted["keys"]
    latest = extracted["latest_version"]
    raw = keys[latest]

    one = chat.decrypt_conversation_key(encrypted_blob)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const prepared = chat.prepareConversationKeyChange({ publicKeys: participants });
    // prepared.conversationKey: Uint8Array for encryptMessage
    // prepared.participantKeys / prepared.actionSignatures: POST body fields

    const extracted = chat.extractConversationKeys(keyChangeBlobs);
    const raw = extracted.keys[extracted.latestVersion!];

    const one = chat.decryptConversationKey(encryptedBlob);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let prepared = chat.prepare_conversation_key_change(
        ConversationKeyChangeParams::new(participants),
    )?;
    let extracted = chat.extract_conversation_keys(&key_change_blobs);
    let latest = extracted.latest_version.as_deref().unwrap_or_default();
    let raw = &extracted.keys[latest];
    let one = chat.decrypt_conversation_key(&encrypted_blob)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    prepared, err := chat.PrepareConversationKeyChange(chatxdk.ConversationKeyChangeParams{
        PublicKeys: participants,
    })
    // prepared.ConversationKey feeds EncryptMessage
    // prepared.ParticipantKeys / prepared.ActionSignatures: POST body fields
    extracted, err := chat.ExtractConversationKeys(keyChangeBlobs)
    one, err := chat.DecryptConversationKey(encryptedBlob)
    _ = prepared
    _ = extracted
    _ = one
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    var prepared = chat.PrepareConversationKeyChange(new ConversationKeyChangeParams(participants));
    var extracted = chat.ExtractConversationKeys(keyChangeBlobs);
    var raw = extracted.Keys[extracted.LatestVersion];
    var one = chat.DecryptConversationKey(encryptedBlob);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    PreparedConversationChange prepared =
            chat.prepareConversationKeyChange(new ConversationKeyChangeParams(participants));
    ConversationKeyBundle extracted = chat.extractConversationKeys(keyChangeBlobs);
    byte[] raw = extracted.keys.get(extracted.latestVersion);
    byte[] one = chat.decryptConversationKey(encryptedBlob);
    ```
  </Tab>
</Tabs>

For group create and member adds, pass the params each method needs (member/admin id lists for `prepare_group_create`; new plus current roster for `prepare_group_members_change`); see [Groups](/xchat/groups#create-the-group-and-establish-keys) for samples. Both return **two** action signatures; the POST must include both.

***

## Decrypt

**`decrypt_events`** is for history and backlog: it pulls conversation keys from the stream, returns decrypted messages, and **collects** per-event errors instead of failing the whole batch. **`decrypt_event`** is for a single live event; it raises/throws on failure.

Pass **signing keys** so the SDK can verify senders. Map API public-key fields into `SigningKeyEntry`: `public_key_version` → `public_key_version` (same name), `signing_public_key` → `public_key`, `public_key` → `identity_public_key`, plus `identity_public_key_signature` and `user_id`.

Two opt-in session stores let you omit the per-call key arguments:

* **`set_signing_keys(entries)`** stores participant signing keys; a decrypt call that omits (or passes an empty) signing-keys argument uses the store instead. Verification itself is unchanged: keys enter the store only through this call, never from the events being decrypted. Each call replaces the previous set.
* **`set_cache_keys(true)`** enables the conversation-key cache (off by default). While enabled, `decrypt_events` caches, per conversation, the latest key whose key change carried a valid signature; `decrypt_event` falls back to it when its conversation-keys argument is omitted, and the encrypt helpers resolve an omitted conversation key from it. Disabling clears the cache.

An explicit non-empty argument always wins over the stores. Explicit per-call arguments remain first-class, and are the right choice for serverless or multi-instance deployments, where a request can land on a fresh instance whose stores are empty.

Verification is mandatory by default: omitting signing keys never skips it. With nothing passed and nothing stored, signed events fail (collected in `errors` for `decrypt_events`, thrown for `decrypt_event`). To actually skip verification you must first call `set_reject_unverified(false)` (not recommended in production).

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    signing_keys = [{
        "user_id": uid,
        "public_key_version": row["public_key_version"],
        "public_key": row["signing_public_key"],
        "identity_public_key": row["public_key"],
        "identity_public_key_signature": row["identity_public_key_signature"],
    } for row in api_public_keys]

    result = chat.decrypt_events(raw_events, signing_keys)
    for idx, msg in (result.get("errors") or {}).items():
        log.warning("event %s failed: %s", idx, msg)
    for dm in result["messages"]:
        ev = dm["event"]
        if ev["type"] == "Message":
            text = ev["content"].get("text")

    cached = result["conversation_keys"]["keys"]
    live = chat.decrypt_event(one_event_b64, cached, signing_keys)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const signingKeys = apiPublicKeys.map((row) => ({
      userId: uid,
      publicKeyVersion: row.public_key_version,
      publicKey: row.signing_public_key,
      identityPublicKey: row.public_key,
      identityPublicKeySignature: row.identity_public_key_signature,
    }));

    const result = chat.decryptEvents(rawEvents, signingKeys);
    for (const [idx, msg] of Object.entries(result.errors ?? {})) {
      console.warn(`event ${idx} failed: ${msg}`);
    }
    const cached = result.conversationKeys.keys;
    const live = chat.decryptEvent(oneEventB64, cached, signingKeys);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let result = chat.decrypt_events(&raw_events, &signing_keys);
    for (idx, msg) in &result.errors {
        eprintln!("event {idx} failed: {msg}");
    }
    let cached = &result.conversation_keys.keys;
    let live = chat.decrypt_event(one_event_b64, cached, &signing_keys)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    result, err := chat.DecryptEvents(rawEvents, signingKeys)
    for idx, msg := range result.Errors {
        log.Printf("event %s failed: %s", idx, msg)
    }
    cached := result.ConversationKeys.Keys
    live, err := chat.DecryptEvent(oneEventB64, cached, signingKeys)
    _ = live
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    var result = chat.DecryptEvents(rawEvents, signingKeys);
    foreach (var kv in result.Errors) { /* kv.Key = event index, kv.Value = error */ }
    var cached = result.ConversationKeys.Keys;
    var live = chat.DecryptEvent(oneEventB64, cached, signingKeys);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    DecryptEventsResult result = chat.decryptEvents(rawEvents, signingKeys);
    Map<String, byte[]> cached = result.conversationKeys.keys;
    JsonNode live = chat.decryptEvent(oneEventB64, cached, signingKeys);
    ```
  </Tab>
</Tabs>

***

## Encrypt and send helpers

**`encrypt_message(conversation_id, text)`** builds the signed ciphertext for a text message; optional `entities`, `attachments` (via `media_hash_key`), `should_notify`, and `ttl_msec`. The sender identity resolves from the session (`set_identity`) and the conversation key from the opt-in key cache (`set_cache_keys`), or pass `sender_id` / `signing_key_version` and `conversation_key` + `conversation_key_version` explicitly. The SDK generates the **`message_id`** (a UUID embedded in the signed event) and returns it on the payload. Never mint your own; reuse the same payload on retries so an id is never minted twice. Map the payload into the send-message body: `message_id` → **`message_id`**, `encrypted_content` → **`encoded_message_create_event`**, `encoded_event_signature` → **`encoded_message_event_signature`**.

**Replies are event-based.** `encrypt_reply(conversation_id, text, reply_to_event)` takes the base64 raw event being replied to. The SDK derives the quoted preview (sequence id, sender, text, entities, attachments) from it and embeds the signed original in the outgoing message so recipients can validate the quote. Pass `reply_to_ckces` (the raw key-change events) when the original was encrypted under an older key version than the reply. When the original was **edited**, pass the raw edit event as `reply_to_edit_event`: the preview then quotes what the message says now (its text and entities come from the edit), and the edit travels alongside the original for the receiver to check. The explicit `reply_to_*` fields remain as overrides for callers that no longer hold the raw event.

**Reactions are event-based too.** `encrypt_add_reaction(target_event, emoji)` and `encrypt_remove_reaction(...)` derive the conversation id and target sequence id from the raw event being reacted to; the same params can add and later remove a reaction. Set `conversation_id` and `target_message_sequence_id` explicitly only when you no longer hold the raw event.

On the receiving side, a decrypted message that quotes a reply carries **`reply_preview_validation`** (`"Valid"` / `"Invalid"`; the JS binding uses `'valid'` / `'invalid'`): the SDK verified the embedded original's signature against your signing keys (never a key carried in the event), decrypted it, and compared the quoted content and author against it. When the preview embeds an edit event, the SDK verifies the edit the same way (same conversation, same author as the original) and checks the quoted text against the edited contents rather than the pre-edit text. The field is absent when the message carries no preview or the preview embeds no original. Treat `Invalid` previews as untrusted: the message itself is authentic, but the quoted material is not. Render quotes only from the validated original.

**`encrypt` / `decrypt`** are for UTF-8 metadata under the conversation key (for example an encrypted group name), not message envelopes. **`encrypt_stream` / `decrypt_stream`** encrypt attachment bytes; see [Media](/xchat/media). Low-level **`sign` / `verify` / `verify_key_binding`** support advanced flows; conversation-key changes, group creates, and member adds are signed by the [prepare methods](#conversation-keys).

The conversation id passed to `encrypt_message` / `encrypt_reply` can be any form you hold (`A:B` from events, `A-B` from listings or URL paths in either order, or the bare recipient user id); the SDK canonicalizes it before signing. Group ids (prefixed with `g`) pass through unchanged.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    payload = chat.encrypt_message(
        conversation_id, "Hello",
        # Optional keyword args: entities, attachments, should_notify, ttl_msec
    )
    body = {
        "message_id": payload.message_id,
        "encoded_message_create_event": payload.encrypted_content,
        "encoded_message_event_signature": payload.encoded_event_signature,
    }
    # POST body to /2/chat/conversations/{id}/messages

    # Preview derived from + embedded raw event so recipients can validate;
    # add reply_to_ckces=[...] when the original used an older key version
    reply = chat.encrypt_reply(conversation_id, "Sounds good", original_event_b64)

    # Conversation and target derived from the raw event
    add = chat.encrypt_add_reaction(original_event_b64, "👍")
    remove = chat.encrypt_remove_reaction(original_event_b64, "👍")

    name_ct = chat.encrypt("Group title", raw_conversation_key)
    title = chat.decrypt(name_ct, raw_conversation_key)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const payload = chat.encryptMessage({
      conversationId,
      text: 'Hello',
      // Optional: entities, attachments, shouldNotify, ttlMsec
    });
    const body = {
      message_id: payload.messageId,
      encoded_message_create_event: payload.encryptedContent,
      encoded_message_event_signature: payload.encodedEventSignature,
    };
    // POST body to /2/chat/conversations/{id}/messages

    // Preview derived from + embedded raw event so recipients can validate;
    // add replyToCkces: [...] when the original used an older key version
    const reply = chat.encryptReply({
      conversationId,
      text: 'Sounds good',
      replyToEvent: originalEventB64,
    });

    // Conversation and target derived from the raw event
    const add = chat.encryptAddReaction({ emoji: '👍', targetEvent: originalEventB64 });
    const remove = chat.encryptRemoveReaction({ emoji: '👍', targetEvent: originalEventB64 });

    const nameCt = chat.encrypt('Group title', rawConversationKey);
    const title = chat.decrypt(nameCt, rawConversationKey);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let payload = chat.encrypt_message(EncryptMessageParams::new(conversation_id, "Hello"))?;
    // Send body: payload.message_id → message_id,
    // payload.encrypted_content → encoded_message_create_event,
    // payload.encoded_event_signature → encoded_message_event_signature

    // Preview derived from + embedded raw event so recipients can validate;
    // set params.reply_to_ckces when the original used an older key version
    let reply = chat.encrypt_reply(EncryptReplyParams::new(
        conversation_id, "Sounds good", original_event_b64,
    ))?;

    // Conversation and target derived from the raw event
    let reaction = EncryptReactionParams::new(original_event_b64, "👍");
    let add = chat.encrypt_add_reaction(&reaction)?;
    let remove = chat.encrypt_remove_reaction(&reaction)?;

    // conv_key: XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
    let name_ct = chat.encrypt("Group title", &conv_key)?;
    let title = chat.decrypt(&name_ct, &conv_key)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    payload, err := chat.EncryptMessage(chatxdk.EncryptMessageParams{
        ConversationID: conversationID,
        Text:           "Hello",
    })
    // Send body: payload.MessageID → message_id,
    // payload.EncryptedContent → encoded_message_create_event,
    // payload.EncodedEventSignature → encoded_message_event_signature

    // Preview derived from + embedded raw event so recipients can validate;
    // set ReplyToCkces when the original used an older key version
    reply, err := chat.EncryptReply(chatxdk.EncryptReplyParams{
        ConversationID: conversationID,
        Text:           "Sounds good",
        ReplyToEvent:   originalEventB64,
    })

    // Conversation and target derived from the raw event
    reaction := chatxdk.EncryptReactionParams{Emoji: "👍", TargetEvent: originalEventB64}
    add, err := chat.EncryptAddReaction(reaction)
    remove, err := chat.EncryptRemoveReaction(reaction)

    nameCt, err := chat.Encrypt("Group title", rawKey)
    title, err := chat.Decrypt(nameCt, rawKey)
    _ = payload
    _ = reply
    _ = add
    _ = remove
    _ = title
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    var payload = chat.EncryptMessage(new EncryptMessageParams(conversationId, "Hello"));
    // Send body: payload.MessageId → message_id,
    // payload.EncryptedContent → encoded_message_create_event,
    // payload.EncodedEventSignature → encoded_message_event_signature

    // Preview derived from + embedded raw event so recipients can validate;
    // set ReplyToCkces when the original used an older key version
    var reply = chat.EncryptReply(new EncryptReplyParams(conversationId, "Sounds good", originalEventB64));

    // Conversation and target derived from the raw event
    var reaction = new EncryptReactionParams(originalEventB64, "👍");
    var add = chat.EncryptAddReaction(reaction);
    var remove = chat.EncryptRemoveReaction(reaction);

    var nameCt = chat.Encrypt("Group title", rawKey);
    var title = chat.Decrypt(nameCt, rawKey);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    SendPayload payload = chat.encryptMessage(new EncryptMessageParams(conversationId, "Hello"));
    // Send body: payload.messageId → message_id,
    // payload.encryptedContent → encoded_message_create_event,
    // payload.encodedEventSignature → encoded_message_event_signature

    // Preview derived from + embedded raw event so recipients can validate;
    // set replyToCkces when the original used an older key version
    SendPayload reply =
            chat.encryptReply(new EncryptReplyParams(conversationId, "Sounds good", originalEventB64));

    // Conversation and target derived from the raw event
    EncryptReactionParams reaction = new EncryptReactionParams(originalEventB64, "👍");
    SendPayload add = chat.encryptAddReaction(reaction);
    SendPayload remove = chat.encryptRemoveReaction(reaction);

    String nameCt = chat.encrypt("Group title", rawKey);
    String title = chat.decrypt(nameCt, rawKey);
    ```
  </Tab>
</Tabs>

***

## Media streams

Encrypt file bytes with the **same** conversation key used for text, upload via Chat media APIs, and attach **`media_hash_key`** on `encrypt_message`. This is not the Posts media model (`expansions=attachments.media_keys`). Full upload/download flow: [Media](/xchat/media).

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    ciphertext = chat.encrypt_stream(file_bytes, raw_conversation_key)
    # Upload `ciphertext`; the `media_hash_key` you attach on encrypt_message
    # comes from the media-upload finalize step, not from encrypt_stream.

    plain = chat.decrypt_stream(ciphertext, raw_conversation_key)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const ciphertext = chat.encryptStream(fileBytes, rawConversationKey);
    // Upload `ciphertext`; mediaHashKey comes from the upload finalize step.
    const plain = chat.decryptStream(ciphertext, rawConversationKey);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // conv_key: &XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
    let ciphertext = chat.encrypt_stream(&file_bytes, &conv_key)?;
    let plain = chat.decrypt_stream(&ciphertext, &conv_key)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    ciphertext, err := chat.EncryptStream(fileBytes, rawKey)
    plain, err := chat.DecryptStream(ciphertext, rawKey)
    _ = plain
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    var ciphertext = chat.EncryptStream(fileBytes, rawKey);
    var plain = chat.DecryptStream(ciphertext, rawKey);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    byte[] ciphertext = chat.encryptStream(fileBytes, rawKey);
    byte[] plain = chat.decryptStream(ciphertext, rawKey);
    ```
  </Tab>
</Tabs>

### Incremental streaming for large media

For large files, avoid holding the whole payload in memory: `stream_encryptor()` / `stream_decryptor()` return a `StreamEncryptor` / `StreamDecryptor` you feed in chunks (about 1 MB each) with `push(chunk)`, then call `finish()` once at the end. On decrypt, `finish()` detects a truncated stream (it fails if input ended before the final frame), so don't treat pushed plaintext as complete until it succeeds.

<Warning>
  **JS/WASM only:** `finish()` consumes and frees the underlying WASM object; never call `free()` after `finish()` (it throws). Call `free()` only to abandon a stream *before* finishing (e.g. on an error path).
</Warning>

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    enc = chat.stream_encryptor(raw_conversation_key)
    chunks = [enc.push(chunk) for chunk in read_in_chunks(file_bytes, 1 << 20)]
    chunks.append(enc.finish())
    ciphertext = b"".join(chunks)

    dec = chat.stream_decryptor(raw_conversation_key)
    out = [dec.push(chunk) for chunk in read_in_chunks(ciphertext, 1 << 20)]
    out.append(dec.finish())  # raises on truncation
    plain = b"".join(out)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const enc = chat.streamEncryptor(rawConversationKey);
    const parts: Uint8Array[] = [];
    try {
      for (const chunk of readInChunks(fileBytes, 1 << 20)) parts.push(enc.push(chunk));
      parts.push(enc.finish()); // consumes + frees enc; do not call enc.free() after this
    } catch (e) {
      enc.free(); // only when abandoning before finish()
      throw e;
    }
    const ciphertext = concat(parts);
    ```
  </Tab>
</Tabs>

***

## Utilities

Base64/hex helpers, MIME sniffing, and image dimensions are available as module-level functions (Python/JS/Rust/Go) or `ChatXdkUtilities` (C#/Java): useful when building attachment metadata without pulling in extra libraries.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from chat_xdk import (
        bytes_to_base64, base64_to_bytes, bytes_to_hex, hex_to_bytes,
        detect_mime_type, detect_image_dimensions,
    )

    b64 = bytes_to_base64(raw)
    raw2 = base64_to_bytes(b64)
    hexed = bytes_to_hex(raw)
    raw3 = hex_to_bytes(hexed)
    mime = detect_mime_type(file_bytes)
    w, h = detect_image_dimensions(file_bytes)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { bytesToBase64, base64ToBytes, bytesToHex, hexToBytes, detectMimeType, detectImageDimensions } from '@xdevplatform/chat-xdk';

    const b64 = bytesToBase64(raw);
    const raw2 = base64ToBytes(b64);
    const hexed = bytesToHex(raw);
    const raw3 = hexToBytes(hexed);
    const mime = detectMimeType(fileBytes);
    const dims = detectImageDimensions(fileBytes);
    const width = dims?.width ?? 0;
    const height = dims?.height ?? 0;
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let b64 = chat_xdk_core::bytes_to_base64(&raw);
    let raw2 = chat_xdk_core::base64_to_bytes(&b64)?;
    let hexed = chat_xdk_core::bytes_to_hex(&raw);
    let raw3 = chat_xdk_core::hex_to_bytes(&hexed);
    let mime = chat_xdk_core::detect_mime_type(&file_bytes);
    let dims = chat_xdk_core::detect_image_dimensions(&file_bytes);
    let (w, h) = dims.map(|d| (d.width, d.height)).unwrap_or((0, 0));
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    b64, _ := chatxdk.BytesToBase64(raw)
    raw2, err := chatxdk.Base64ToBytes(b64)
    hexed, err := chatxdk.BytesToHex(raw)
    raw3, err := chatxdk.HexToBytes(hexed)
    mime, _ := chatxdk.DetectMimeType(fileBytes)
    dims, _ := chatxdk.DetectImageDimensions(fileBytes)
    w, h := dims.Width, dims.Height
    _ = b64
    _ = raw2
    _ = hexed
    _ = raw3
    _ = mime
    _ = w
    _ = h
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    var b64 = ChatXdkUtilities.BytesToBase64(raw);
    var raw2 = ChatXdkUtilities.Base64ToBytes(b64);
    var hexed = ChatXdkUtilities.BytesToHex(raw);
    var raw3 = ChatXdkUtilities.HexToBytes(hexed);
    var mime = ChatXdkUtilities.DetectMimeType(fileBytes);
    var dims = ChatXdkUtilities.DetectImageDimensions(fileBytes);
    var w = dims?.Width ?? 0;
    var h = dims?.Height ?? 0;
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String b64 = ChatXdkUtilities.bytesToBase64(raw);
    byte[] raw2 = ChatXdkUtilities.base64ToBytes(b64);
    String hexed = ChatXdkUtilities.bytesToHex(raw);
    byte[] raw3 = ChatXdkUtilities.hexToBytes(hexed);
    String mime = ChatXdkUtilities.detectMimeType(fileBytes);
    ImageDimensions wh = ChatXdkUtilities.detectImageDimensions(fileBytes);
    long width = wh.width, height = wh.height;
    ```
  </Tab>
</Tabs>

***

## Important types

These conceptual types show up across languages (exact field names differ; JS often uses camelCase event discriminators like `message`):

* **SendPayload**: return value of `encrypt_message` and the other encrypt helpers: the SDK-generated **`message_id`** (a UUID embedded in the signed event; send it as the message's `message_id` and keep it to dedup), `encrypted_content`, `encoded_event_signature`, signature metadata, `conversation_key_version`, and `should_notify`. Map into the Chat API send body.
* **PublicKeyRegistrationPayload**: output of `generate_keypairs` / public-key getters for the add-public-key API.
* **SigningKeyEntry**: sender public material passed into decrypt for signature verification, or stored via `set_signing_keys`.
* **PreparedConversationChange**: output of the three prepare methods: the derived or passed `conversation_id`, the raw `conversation_key` bytes, `conversation_key_version`, `participant_keys` (`user_id`, `encrypted_key`, `public_key_version`), and `action_signatures` (`message_id`, `encoded_message_event_detail`, `signature`, `signature_version`, `public_key_version`, optional `signature_payload`, omitted on key-change signatures because that payload embeds the plaintext key).
* **DecryptEventsResult**: messages, optional errors, and extracted `conversation_keys`. Decrypted messages that quote a reply carry `reply_preview_validation` (see [Encrypt and send helpers](#encrypt-and-send-helpers)).

For complete field lists, use language stubs in the [chat-xdk repo](https://github.com/xdevplatform/chat-xdk) (`docs/API.md`, `*.pyi`, `index.d.ts`).

***

## Errors

Python typically raises **`ValueError`** with a descriptive message (for example an invalid passcode). TypeScript/JavaScript throws **`Error`**. Go returns `(value, error)`. Prefer **`decrypt_events`** for history so one bad event does not abort the batch; inspect the errors collection for partial failures.

Some verification errors are **permanent**. Signatures are immutable and verified by rebuilding the signed payload from the event itself, so an old event that fails with `signature missing or no matching signing key` or an ECDSA mismatch will fail on every future load. No retry, key refresh, or API call can heal it. Treat these as tombstones, not transient errors. Rotating the conversation key starts a clean, verifiable history from that point forward.

***

## Next steps

<CardGroup>
  <Card title="Getting Started" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/xchat/getting-started">
    Wire Chat XDK to the Chat API
  </Card>

  <Card title="Media" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-photo.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=d0986097dcff55478c32801b20440ecc" href="/xchat/media">
    Stream encrypt and media REST
  </Card>

  <Card title="Real-time events" icon="bolt" href="/xchat/real-time-events">
    Webhooks and activity delivery
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/xchat/troubleshooting">
    Common failures
  </Card>
</CardGroup>


# Authentication
Source: https://docs.x.com/xdks/python/authentication

Authenticate the Python XDK with Bearer Token, OAuth 2.0 PKCE, or OAuth 1.0a user context to call X API endpoints and post on behalf of users.

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
3. OAuth 1.0a (User Context)

* **Bearer Token**: Use this for read-only access for endpoints that support app-auth (e.g., searching Post's, streaming endpoints).
* **OAuth 2.0 PKCE**: Secure authentication for scope-based, user-authorized access (e.g. getting authenticated user's Post non\_public metrics)
* **OAuth 1.0a**: Legacy authentication for user-specific operations (e.g., posting on behalf of a user, managing lists)
  Obtain credentials from the [X Developer Console](https://developer.x.com/en/portal/dashboard). You'll need an approved developer account and an app with appropriate permissions (e.g., Read + Write).

## Creating a Client

All authentication flows create a `Client` instance:

```python theme={null}
from xdk import Client
```

### 1. Bearer Token (App-Only)

For read-only operations without user context.
**Steps**:

1. In the Developer Console, generate a Bearer Token for your app.
2. Pass it to the `Client`.
   **Example**:

```python theme={null}
client = Client(bearer_token="XXXXX")
```

**Usage**:

```python theme={null}
# search_recent returns an Iterator, so iterate over it
for page in client.posts.search_recent(query="python", max_results=10):
    if page.data and len(page.data) > 0:
        first_post = page.data[0]
        post_text = first_post.text if hasattr(first_post, 'text') else first_post.get('text', '')
        print(post_text)  # Access first Post
        break
```

### 2. OAuth 2.0 with PKCE (User Context)

This example shows how to use OAuth 2.0 with Proof Key for Code Exchange (PKCE). Use this for user-specific access (e.g. posting on behalf of a user), uploading media for a user etc.).
**Steps**:

1. In the Developer Console, register your app with a redirect URI (e.g., `http://localhost:8080/callback`).
2. Get Client ID (no secret needed for PKCE).
3. Initiate the flow, direct user to auth URL and handle callback.
   **Example** (using a web server for callback):

```python title="Example" expandable lines wrap icon="python" theme={null}
from xdk.oauth2_auth import OAuth2PKCEAuth
from urllib.parse import urlparse
import webbrowser
# Step 1: Create PKCE instance
auth = OAuth2PKCEAuth(
    client_id="YOUR_CLIENT_ID",
    redirect_uri="YOUR_CALLBACK_URL",
    scope="tweet.read users.read offline.access"
)
# Step 2: Get authorization URL
auth_url = auth.get_authorization_url()
print(f"Visit this URL to authorize: {auth_url}")
webbrowser.open(auth_url)
# Step 3: Handle callback (in a real app, use a web framework like Flask)
# Assume callback_url = "http://localhost:8080/callback?code=AUTH_CODE_HERE"
callback_url = input("Paste the full callback URL here: ")
# Step 4: Exchange code for tokens
tokens = auth.fetch_token(authorization_response=callback_url)
access_token = tokens["access_token"]
refresh_token = tokens["refresh_token"]  # Store for renewal
# Step 5: Create client
# Option 1: Use bearer_token (OAuth2 access tokens work as bearer tokens)
client = Client(bearer_token=access_token)
# Option 2: Pass the full token dict for automatic refresh support
# client = Client(token=tokens)
```

**Token Refresh** (automatic in SDK for long-lived sessions):

```python theme={null}
# If access token expires, refresh using stored refresh_token
# The refresh_token method uses the stored token from the OAuth2PKCEAuth instance
tokens = auth.refresh_token()
# Use the refreshed token
client = Client(bearer_token=tokens["access_token"])
# Or pass the full token dict: client = Client(token=tokens)
```

### 3. OAuth 1.0a (User Context)

For legacy applications or specific use cases that require OAuth 1.0a authentication:
**Steps**:

1. In the Developer Console, get your API Key and API Secret.
2. If you already have access tokens, use them directly. Otherwise, complete the OAuth 1.0a flow to obtain them.
3. Create an OAuth1 instance and pass it to the Client.
   **Example** (with existing access tokens):

```python title="Example" lines wrap icon="python" theme={null}
from xdk import Client
from xdk.oauth1_auth import OAuth1
# Step 1: Create OAuth1 instance with credentials
oauth1 = OAuth1(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    callback="http://localhost:8080/callback",
    access_token="YOUR_ACCESS_TOKEN",
    access_token_secret="YOUR_ACCESS_TOKEN_SECRET"
)
# Step 2: Create client with OAuth1
client = Client(auth=oauth1)
# Step 3: Use the client
response = client.users.get_me()
me = response.data
print(me)
```

**Example** (complete OAuth 1.0a flow):

```python title="Example" lines wrap icon="python" theme={null}
from xdk import Client
from xdk.oauth1_auth import OAuth1
import webbrowser
# Step 1: Create OAuth1 instance
oauth1 = OAuth1(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    callback="http://localhost:8080/callback"
)
# Step 2: Get request token
request_token = oauth1.get_request_token()
# Step 3: Get authorization URL
auth_url = oauth1.get_authorization_url(login_with_x=False)
print(f"Visit this URL to authorize: {auth_url}")
webbrowser.open(auth_url)
# Step 4: User authorizes and you receive oauth_verifier
# In a real app, handle this via callback URL
oauth_verifier = input("Enter the OAuth verifier from the callback: ")
# Step 5: Exchange for access token
access_token = oauth1.get_access_token(oauth_verifier)
# Step 6: Create client
client = Client(auth=oauth1)
# Now you can use the client
response = client.users.get_me()
```

**Note**:

* Never hardcode secrets in production; use environment variables or secret managers (e.g., `os.getenv("X_BEARER_TOKEN")`).
* For PKCE, ensure HTTPS for redirect URIs in production.
* The SDK validates tokens and raises `xdk.AuthenticationError` on failures.
  For detailed code examples using the Python XDK, check out our [code samples GitHub repo](https://github.com/xdevplatform/samples/tree/main/python).


# Install
Source: https://docs.x.com/xdks/python/install

Install the Python XDK from PyPI with pip, set up a venv, or build from source for development to start calling X API v2 endpoints in Python 3.8 or higher.

The XDK Python SDK is available directly from the GitHub repository and can be installed via `pip`.

## Prerequisites

* Python 3.8 or higher.
* `pip` and `venv` for virtual environments (recommended).

## Quick Install

Install the XDK from the GitHub subdirectory:

```bash theme={null}
pip install xdk
```

This fetches the latest generated version from the `main` branch.

## Development Install

For development or contributing:

1. Clone the repository:
   ```bash theme={null}
   git clone https://github.com/xdevplatform/xdk.git
   cd xdk/python
   ```
2. Install dependencies in editable mode:
   ```bash theme={null}
   pip install -e .
   ```
   This installs the SDK and its runtime dependencies.
3. (Optional) Install dev dependencies for testing/linting:
   ```bash theme={null}
   pip install -e .[dev]
   ```

## Verification

Test the installation:

```python theme={null}
import xdk
print(xdk.__version__)  # Should print the XDK version
```

**Note:** Since the XDK is generated using the OpenAPI spec, always check the [X API changelog](https://docs.x.com/changelog) and XDK release notes in the repo for any changes.
For detailed code examples using the Python XDK, check out our [code samples GitHub repo](https://github.com/xdevplatform/samples/tree/main/python).


# Python XDK
Source: https://docs.x.com/xdks/python/overview

Overview of the Python XDK, the official X API v2 client library generated from OpenAPI with OAuth, pagination, and streaming support for Python 3.8 and above.

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

* 🔐 **OAuth Support**: Full support for Bearer Token (app-only) auth, OAuth 2.0 with PKCE (user context), and OAuth 1.0.
* 🔄 **Pagination**: Automatically page through large results. The XDK takes care of pagination without requiring you to make multiple API calls using the `next_token`.
* 📡 **Streaming**: Supports real-time data streaming for endpoints like filtered stream that require persistent http connection.
* 🎯 **Comprehensive Coverage**: Supports all X API v2 endpoints including such as search, timelines, filtered-stream and more.
  **Version Compatibility**: Python 3.8+. Tested on CPython and PyPy.
  **License**: [MIT License](https://github.com/xdevplatform/xdk/blob/main/LICENSE)
  For detailed code examples using the Python XDK, check out our [code samples GitHub repo](https://github.com/xdevplatform/samples/tree/main/python).


# Pagination
Source: https://docs.x.com/xdks/python/pagination

Page through X API results in Python using the XDK iterator for automatic next_token handling, or manage pagination_token manually for custom paging logic.

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.
* **Explicit Token Handling**: For flexible manual control when needed by passing `pagination_token` when needed.
* **Max Results Enforcement**: Respect `max_results` per call (up to API limits, e.g., 100 for search).

## Automatic Pagination (Recommended)

Use the `iterate()` method on paginated responses to fetch all results lazily.
**Example: Paginated Search**

```python title="Example" lines wrap icon="python" theme={null}
from xdk import Client
client = Client(bearer_token="your_bearer_token")
# Search with automatic pagination
all_posts = []
for page in client.posts.search_recent(
    query="python",
    max_results=100,  # Per page
    tweet_fields=["created_at", "author_id"]  # Optional expansions
):
    all_posts.extend(page.data)
    print(f"Fetched {len(page.data)} Posts (total: {len(all_posts)})")
print(f"Total tweets: {len(all_posts)}")
```

* The iterator handles `next_token` automatically.
* Stops when no `next_token` is present.
* Supports rate limit backoff to avoid 429 errors.

## Manual Pagination

If you require control over the results for some custom logic (e.g. processing page-by-page), you can still use the `next_token` and do the pagination manually as shown below:

```python title="Example" lines wrap icon="python" theme={null}
# Get first page - search_recent returns an Iterator
first_page = next(client.posts.search_recent(
    query="xdk python sdk",
    max_results=100,
    pagination_token=None  # First page
))
print(f"First page: {len(first_page.data) if first_page.data else 0} Posts")
# Extract next_token from meta
next_token = None
if hasattr(first_page, 'meta') and first_page.meta:
    if hasattr(first_page.meta, 'next_token'):
        next_token = first_page.meta.next_token
    elif isinstance(first_page.meta, dict):
        next_token = first_page.meta.get('next_token')
if next_token:
    second_page = next(client.posts.search_recent(
        query="xdk python sdk",
        max_results=100,
        pagination_token=next_token
    ))
    print(f"Second page: {len(second_page.data) if second_page.data else 0} Posts")
```

**Tips**:

* Always specify `max_results` to optimize (default varies by endpoint).
* Monitor `meta.result_count` for debugging.
* For very large queries, consider async iteration to avoid blocking.
  For detailed code examples using the Python XDK, check out our [code samples GitHub repo](https://github.com/xdevplatform/samples/tree/main/python).


# Quickstart
Source: https://docs.x.com/xdks/python/quickstart

This example showcases how to quickly search for Posts using the XDK using Bearer Token authentication. 1. Log in to the X Developer Console. 2.

This example showcases how to quickly search for Posts using the XDK using Bearer Token authentication.

## Step 1: Install the SDK

```bash theme={null}
pip install xdk
```

## Step 2: Get Your Bearer Token

1. Log in to the [X Developer Console](https://developer.x.com/en/portal/dashboard).
2. Create or select an app.
3. Under "Keys and Tokens," generate a Bearer Token (app-only auth).

## Step 3: Write and Run Your First Script

Create a file `quickstart.py`:

```python title="Example" lines wrap icon="python" theme={null}
# Import the client
from xdk import Client
# Replace with your actual Bearer Token
client = Client(bearer_token="YOUR_BEARER_TOKEN_HERE")
# Fetch recent Posts mentioning "api"
# search_recent returns an Iterator, so iterate over it
for page in client.posts.search_recent(query="api", max_results=10):
    if page.data and len(page.data) > 0:
        # Access first Post - Pydantic models support both attribute and dict access
        first_post = page.data[0]
        post_text = first_post.text if hasattr(first_post, 'text') else first_post.get('text', '')
        print(f"Latest Post: {post_text}")
        break
    else:
        print("No Posts found.")
        break
```

Run it:

```bash theme={null}
python quickstart.py
```

**Expected Output**:

```
Latest Post: Exciting updates on XDK Python SDK!
```

**Troubleshooting**: If you get a 401 error, double-check your Bearer Token. For rate limits (429), wait and retry.

## Next Steps

* Explore [Authentication](/xdks/python/authentication) to understand how to use Bearer Token (app-only) auth, OAuth 2.0 with PKCE (user context), and OAuth 1.0a (legacy user context).
* Learn about [Pagination](/xdks/python/pagination) for use-cases where you want large number of results returned without worrying about making multiple API calls.
* Dive into [Streaming](/xdks/python/streaming) to learn how to work with real-time data.
  For detailed code examples using the Python XDK, check out our [code samples GitHub repo](https://github.com/xdevplatform/samples/tree/main/python).


# X API SDK Documentation
Source: https://docs.x.com/xdks/python/reference/index

Index of the X API Python SDK reference: top-level package, client modules, and request/response models for every X API v2 endpoint group.

Welcome to the X API SDK documentation.

# API Reference:

* [xdk](/xdks/python/reference/modules)
  * [xdk package](/xdks/python/reference/xdk)


# xdk
Source: https://docs.x.com/xdks/python/reference/modules

List of every module in the X API Python SDK reference, linking to clients, request/response models, and helpers for each X API v2 endpoint group.

<AccordionGroup>
  <Accordion title="Packages">
    <Accordion title="Account Activity">
      * [Client](/xdks/python/reference/xdk.account_activity.client)
      * [Core](/xdks/python/reference/xdk.account_activity)
      * [Models](/xdks/python/reference/xdk.account_activity.models)
    </Accordion>

    <Accordion title="Activity">
      * [Client](/xdks/python/reference/xdk.activity.client)
      * [Core](/xdks/python/reference/xdk.activity)
      * [Models](/xdks/python/reference/xdk.activity.models)
    </Accordion>

    <Accordion title="Client">
      * [Client](/xdks/python/reference/xdk.client)
    </Accordion>

    <Accordion title="Communities">
      * [Client](/xdks/python/reference/xdk.communities.client)
      * [Core](/xdks/python/reference/xdk.communities)
      * [Models](/xdks/python/reference/xdk.communities.models)
    </Accordion>

    <Accordion title="Community Notes">
      * [Client](/xdks/python/reference/xdk.community_notes.client)
      * [Core](/xdks/python/reference/xdk.community_notes)
      * [Models](/xdks/python/reference/xdk.community_notes.models)
    </Accordion>

    <Accordion title="Compliance">
      * [Client](/xdks/python/reference/xdk.compliance.client)
      * [Core](/xdks/python/reference/xdk.compliance)
      * [Models](/xdks/python/reference/xdk.compliance.models)
    </Accordion>

    <Accordion title="Connections">
      * [Client](/xdks/python/reference/xdk.connections.client)
      * [Core](/xdks/python/reference/xdk.connections)
      * [Models](/xdks/python/reference/xdk.connections.models)
    </Accordion>

    <Accordion title="Direct Messages">
      * [Client](/xdks/python/reference/xdk.direct_messages.client)
      * [Core](/xdks/python/reference/xdk.direct_messages)
      * [Models](/xdks/python/reference/xdk.direct_messages.models)
    </Accordion>

    <Accordion title="General">
      * [Client](/xdks/python/reference/xdk.general.client)
      * [Core](/xdks/python/reference/xdk.general)
      * [Models](/xdks/python/reference/xdk.general.models)
    </Accordion>

    <Accordion title="Lists">
      * [Client](/xdks/python/reference/xdk.lists.client)
      * [Core](/xdks/python/reference/xdk.lists)
      * [Models](/xdks/python/reference/xdk.lists.models)
    </Accordion>

    <Accordion title="Media">
      * [Client](/xdks/python/reference/xdk.media.client)
      * [Core](/xdks/python/reference/xdk.media)
      * [Models](/xdks/python/reference/xdk.media.models)
    </Accordion>

    <Accordion title="News">
      * [Client](/xdks/python/reference/xdk.news.client)
      * [Core](/xdks/python/reference/xdk.news)
      * [Models](/xdks/python/reference/xdk.news.models)
    </Accordion>

    <Accordion title="Oauth1 Auth">
      * [Core](/xdks/python/reference/xdk.oauth1_auth)
    </Accordion>

    <Accordion title="Oauth2 Auth">
      * [Core](/xdks/python/reference/xdk.oauth2_auth)
    </Accordion>

    <Accordion title="Paginator">
      * [Core](/xdks/python/reference/xdk.paginator)
    </Accordion>

    <Accordion title="Posts">
      * [Client](/xdks/python/reference/xdk.posts.client)
      * [Core](/xdks/python/reference/xdk.posts)
      * [Models](/xdks/python/reference/xdk.posts.models)
    </Accordion>

    <Accordion title="Spaces">
      * [Client](/xdks/python/reference/xdk.spaces.client)
      * [Core](/xdks/python/reference/xdk.spaces)
      * [Models](/xdks/python/reference/xdk.spaces.models)
    </Accordion>

    <Accordion title="Stream">
      * [Client](/xdks/python/reference/xdk.stream.client)
      * [Core](/xdks/python/reference/xdk.stream)
      * [Models](/xdks/python/reference/xdk.stream.models)
    </Accordion>

    <Accordion title="Streaming">
      * [Core](/xdks/python/reference/xdk.streaming)
    </Accordion>

    <Accordion title="Trends">
      * [Client](/xdks/python/reference/xdk.trends.client)
      * [Core](/xdks/python/reference/xdk.trends)
      * [Models](/xdks/python/reference/xdk.trends.models)
    </Accordion>

    <Accordion title="Usage">
      * [Client](/xdks/python/reference/xdk.usage.client)
      * [Core](/xdks/python/reference/xdk.usage)
      * [Models](/xdks/python/reference/xdk.usage.models)
    </Accordion>

    <Accordion title="Users">
      * [Client](/xdks/python/reference/xdk.users.client)
      * [Core](/xdks/python/reference/xdk.users)
      * [Models](/xdks/python/reference/xdk.users.models)
    </Accordion>

    <Accordion title="Webhooks">
      * [Client](/xdks/python/reference/xdk.webhooks.client)
      * [Core](/xdks/python/reference/xdk.webhooks)
      * [Models](/xdks/python/reference/xdk.webhooks.models)
    </Accordion>

    <Accordion title="Xdk">
      * [Core](/xdks/python/reference/xdk)
    </Accordion>
  </Accordion>
</AccordionGroup>


# Client
Source: https://docs.x.com/xdks/python/reference/xdk

Reference for the xdk top-level Python package in the X API SDK. Re-exported clients, models, and utilities for calling the X API v2 from Python.

## Subpackages

* [xdk.account\_activity package](/xdks/python/reference/xdk.account_activity)
  * [Submodules](/xdks/python/reference/xdk.account_activity#submodules)
    * [xdk.account\_activity.client module](/xdks/python/reference/xdk.account_activity.client)
      * [`AccountActivityClient`](/xdks/python/reference/xdk.account_activity.client#xdk.account_activity.client.AccountActivityClient)
    * [xdk.account\_activity.models module](/xdks/python/reference/xdk.account_activity.models)
      * [`CreateReplayJobResponse`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.CreateReplayJobResponse)
      * [`CreateSubscriptionRequest`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.CreateSubscriptionRequest)
      * [`CreateSubscriptionResponse`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.CreateSubscriptionResponse)
      * [`DeleteSubscriptionResponse`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.DeleteSubscriptionResponse)
      * [`GetSubscriptionCountResponse`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.GetSubscriptionCountResponse)
      * [`GetSubscriptionsResponse`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.GetSubscriptionsResponse)
      * [`ValidateSubscriptionResponse`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.ValidateSubscriptionResponse)
  * [Module contents](/xdks/python/reference/xdk.account_activity#module-xdk.account_activity)
    * [`AccountActivityClient`](/xdks/python/reference/xdk.account_activity#xdk.account_activity.AccountActivityClient)
      * [`AccountActivityClient.__init__()`](/xdks/python/reference/xdk.account_activity#xdk.account_activity.AccountActivityClient.__init__)
      * [`AccountActivityClient.create_replay_job()`](/xdks/python/reference/xdk.account_activity#xdk.account_activity.AccountActivityClient.create_replay_job)
      * [`AccountActivityClient.create_subscription()`](/xdks/python/reference/xdk.account_activity#xdk.account_activity.AccountActivityClient.create_subscription)
      * [`AccountActivityClient.delete_subscription()`](/xdks/python/reference/xdk.account_activity#xdk.account_activity.AccountActivityClient.delete_subscription)
      * [`AccountActivityClient.get_subscription_count()`](/xdks/python/reference/xdk.account_activity#xdk.account_activity.AccountActivityClient.get_subscription_count)
      * [`AccountActivityClient.get_subscriptions()`](/xdks/python/reference/xdk.account_activity#xdk.account_activity.AccountActivityClient.get_subscriptions)
      * [`AccountActivityClient.validate_subscription()`](/xdks/python/reference/xdk.account_activity#xdk.account_activity.AccountActivityClient.validate_subscription)
* [xdk.activity package](/xdks/python/reference/xdk.activity)
  * [Submodules](/xdks/python/reference/xdk.activity#submodules)
    * [xdk.activity.client module](/xdks/python/reference/xdk.activity.client)
      * [`ActivityClient`](/xdks/python/reference/xdk.activity.client#xdk.activity.client.ActivityClient)
    * [xdk.activity.models module](/xdks/python/reference/xdk.activity.models)
      * [`CreateSubscriptionRequest`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.CreateSubscriptionRequest)
      * [`CreateSubscriptionResponse`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.CreateSubscriptionResponse)
      * [`DeleteSubscriptionResponse`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.DeleteSubscriptionResponse)
      * [`GetSubscriptionsResponse`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.GetSubscriptionsResponse)
      * [`StreamResponse`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.StreamResponse)
      * [`UpdateSubscriptionRequest`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.UpdateSubscriptionRequest)
      * [`UpdateSubscriptionResponse`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.UpdateSubscriptionResponse)
  * [Module contents](/xdks/python/reference/xdk.activity#module-xdk.activity)
    * [`ActivityClient`](/xdks/python/reference/xdk.activity#xdk.activity.ActivityClient)
      * [`ActivityClient.__init__()`](/xdks/python/reference/xdk.activity#xdk.activity.ActivityClient.__init__)
      * [`ActivityClient.create_subscription()`](/xdks/python/reference/xdk.activity#xdk.activity.ActivityClient.create_subscription)
      * [`ActivityClient.delete_subscription()`](/xdks/python/reference/xdk.activity#xdk.activity.ActivityClient.delete_subscription)
      * [`ActivityClient.get_subscriptions()`](/xdks/python/reference/xdk.activity#xdk.activity.ActivityClient.get_subscriptions)
      * [`ActivityClient.stream()`](/xdks/python/reference/xdk.activity#xdk.activity.ActivityClient.stream)
      * [`ActivityClient.update_subscription()`](/xdks/python/reference/xdk.activity#xdk.activity.ActivityClient.update_subscription)
* [xdk.communities package](/xdks/python/reference/xdk.communities)
  * [Submodules](/xdks/python/reference/xdk.communities#submodules)
    * [xdk.communities.client module](/xdks/python/reference/xdk.communities.client)
      * [`CommunitiesClient`](/xdks/python/reference/xdk.communities.client#xdk.communities.client.CommunitiesClient)
    * [xdk.communities.models module](/xdks/python/reference/xdk.communities.models)
      * [`GetByIdResponse`](/xdks/python/reference/xdk.communities.models#xdk.communities.models.GetByIdResponse)
      * [`SearchResponse`](/xdks/python/reference/xdk.communities.models#xdk.communities.models.SearchResponse)
  * [Module contents](/xdks/python/reference/xdk.communities#module-xdk.communities)
    * [`CommunitiesClient`](/xdks/python/reference/xdk.communities#xdk.communities.CommunitiesClient)
      * [`CommunitiesClient.__init__()`](/xdks/python/reference/xdk.communities#xdk.communities.CommunitiesClient.__init__)
      * [`CommunitiesClient.get_by_id()`](/xdks/python/reference/xdk.communities#xdk.communities.CommunitiesClient.get_by_id)
      * [`CommunitiesClient.search()`](/xdks/python/reference/xdk.communities#xdk.communities.CommunitiesClient.search)
* [xdk.community\_notes package](/xdks/python/reference/xdk.community_notes)
  * [Submodules](/xdks/python/reference/xdk.community_notes#submodules)
    * [xdk.community\_notes.client module](/xdks/python/reference/xdk.community_notes.client)
      * [`CommunityNotesClient`](/xdks/python/reference/xdk.community_notes.client#xdk.community_notes.client.CommunityNotesClient)
    * [xdk.community\_notes.models module](/xdks/python/reference/xdk.community_notes.models)
      * [`CreateRequest`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.CreateRequest)
      * [`CreateResponse`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.CreateResponse)
      * [`DeleteResponse`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.DeleteResponse)
      * [`EvaluateRequest`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.EvaluateRequest)
      * [`EvaluateResponse`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.EvaluateResponse)
      * [`SearchEligiblePostsResponse`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.SearchEligiblePostsResponse)
      * [`SearchWrittenResponse`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.SearchWrittenResponse)
  * [Module contents](/xdks/python/reference/xdk.community_notes#module-xdk.community_notes)
    * [`CommunityNotesClient`](/xdks/python/reference/xdk.community_notes#xdk.community_notes.CommunityNotesClient)
      * [`CommunityNotesClient.__init__()`](/xdks/python/reference/xdk.community_notes#xdk.community_notes.CommunityNotesClient.__init__)
      * [`CommunityNotesClient.create()`](/xdks/python/reference/xdk.community_notes#xdk.community_notes.CommunityNotesClient.create)
      * [`CommunityNotesClient.delete()`](/xdks/python/reference/xdk.community_notes#xdk.community_notes.CommunityNotesClient.delete)
      * [`CommunityNotesClient.evaluate()`](/xdks/python/reference/xdk.community_notes#xdk.community_notes.CommunityNotesClient.evaluate)
      * [`CommunityNotesClient.search_eligible_posts()`](/xdks/python/reference/xdk.community_notes#xdk.community_notes.CommunityNotesClient.search_eligible_posts)
      * [`CommunityNotesClient.search_written()`](/xdks/python/reference/xdk.community_notes#xdk.community_notes.CommunityNotesClient.search_written)
* [xdk.compliance package](/xdks/python/reference/xdk.compliance)
  * [Submodules](/xdks/python/reference/xdk.compliance#submodules)
    * [xdk.compliance.client module](/xdks/python/reference/xdk.compliance.client)
      * [`ComplianceClient`](/xdks/python/reference/xdk.compliance.client#xdk.compliance.client.ComplianceClient)
    * [xdk.compliance.models module](/xdks/python/reference/xdk.compliance.models)
      * [`CreateJobsRequest`](/xdks/python/reference/xdk.compliance.models#xdk.compliance.models.CreateJobsRequest)
      * [`CreateJobsResponse`](/xdks/python/reference/xdk.compliance.models#xdk.compliance.models.CreateJobsResponse)
      * [`GetJobsByIdResponse`](/xdks/python/reference/xdk.compliance.models#xdk.compliance.models.GetJobsByIdResponse)
      * [`GetJobsResponse`](/xdks/python/reference/xdk.compliance.models#xdk.compliance.models.GetJobsResponse)
  * [Module contents](/xdks/python/reference/xdk.compliance#module-xdk.compliance)
    * [`ComplianceClient`](/xdks/python/reference/xdk.compliance#xdk.compliance.ComplianceClient)
      * [`ComplianceClient.__init__()`](/xdks/python/reference/xdk.compliance#xdk.compliance.ComplianceClient.__init__)
      * [`ComplianceClient.create_jobs()`](/xdks/python/reference/xdk.compliance#xdk.compliance.ComplianceClient.create_jobs)
      * [`ComplianceClient.get_jobs()`](/xdks/python/reference/xdk.compliance#xdk.compliance.ComplianceClient.get_jobs)
      * [`ComplianceClient.get_jobs_by_id()`](/xdks/python/reference/xdk.compliance#xdk.compliance.ComplianceClient.get_jobs_by_id)
* [xdk.connections package](/xdks/python/reference/xdk.connections)
  * [Submodules](/xdks/python/reference/xdk.connections#submodules)
    * [xdk.connections.client module](/xdks/python/reference/xdk.connections.client)
      * [`ConnectionsClient`](/xdks/python/reference/xdk.connections.client#xdk.connections.client.ConnectionsClient)
    * [xdk.connections.models module](/xdks/python/reference/xdk.connections.models)
      * [`DeleteAllResponse`](/xdks/python/reference/xdk.connections.models#xdk.connections.models.DeleteAllResponse)
  * [Module contents](/xdks/python/reference/xdk.connections#module-xdk.connections)
    * [`ConnectionsClient`](/xdks/python/reference/xdk.connections#xdk.connections.ConnectionsClient)
      * [`ConnectionsClient.__init__()`](/xdks/python/reference/xdk.connections#xdk.connections.ConnectionsClient.__init__)
      * [`ConnectionsClient.delete_all()`](/xdks/python/reference/xdk.connections#xdk.connections.ConnectionsClient.delete_all)
* [xdk.direct\_messages package](/xdks/python/reference/xdk.direct_messages)
  * [Submodules](/xdks/python/reference/xdk.direct_messages#submodules)
    * [xdk.direct\_messages.client module](/xdks/python/reference/xdk.direct_messages.client)
      * [`DirectMessagesClient`](/xdks/python/reference/xdk.direct_messages.client#xdk.direct_messages.client.DirectMessagesClient)
    * [xdk.direct\_messages.models module](/xdks/python/reference/xdk.direct_messages.models)
      * [`CreateByConversationIdRequest`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateByConversationIdRequest)
      * [`CreateByConversationIdResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateByConversationIdResponse)
      * [`CreateByParticipantIdRequest`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateByParticipantIdRequest)
      * [`CreateByParticipantIdResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateByParticipantIdResponse)
      * [`CreateConversationRequest`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateConversationRequest)
      * [`CreateConversationResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateConversationResponse)
      * [`DeleteEventsResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.DeleteEventsResponse)
      * [`GetEventsByConversationIdResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.GetEventsByConversationIdResponse)
      * [`GetEventsByIdResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.GetEventsByIdResponse)
      * [`GetEventsByParticipantIdResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.GetEventsByParticipantIdResponse)
      * [`GetEventsResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.GetEventsResponse)
  * [Module contents](/xdks/python/reference/xdk.direct_messages#module-xdk.direct_messages)
    * [`DirectMessagesClient`](/xdks/python/reference/xdk.direct_messages#xdk.direct_messages.DirectMessagesClient)
      * [`DirectMessagesClient.__init__()`](/xdks/python/reference/xdk.direct_messages#xdk.direct_messages.DirectMessagesClient.__init__)
      * [`DirectMessagesClient.create_by_conversation_id()`](/xdks/python/reference/xdk.direct_messages#xdk.direct_messages.DirectMessagesClient.create_by_conversation_id)
      * [`DirectMessagesClient.create_by_participant_id()`](/xdks/python/reference/xdk.direct_messages#xdk.direct_messages.DirectMessagesClient.create_by_participant_id)
      * [`DirectMessagesClient.create_conversation()`](/xdks/python/reference/xdk.direct_messages#xdk.direct_messages.DirectMessagesClient.create_conversation)
      * [`DirectMessagesClient.delete_events()`](/xdks/python/reference/xdk.direct_messages#xdk.direct_messages.DirectMessagesClient.delete_events)
      * [`DirectMessagesClient.get_events()`](/xdks/python/reference/xdk.direct_messages#xdk.direct_messages.DirectMessagesClient.get_events)
      * [`DirectMessagesClient.get_events_by_conversation_id()`](/xdks/python/reference/xdk.direct_messages#xdk.direct_messages.DirectMessagesClient.get_events_by_conversation_id)
      * [`DirectMessagesClient.get_events_by_id()`](/xdks/python/reference/xdk.direct_messages#xdk.direct_messages.DirectMessagesClient.get_events_by_id)
      * [`DirectMessagesClient.get_events_by_participant_id()`](/xdks/python/reference/xdk.direct_messages#xdk.direct_messages.DirectMessagesClient.get_events_by_participant_id)
* [xdk.general package](/xdks/python/reference/xdk.general)
  * [Submodules](/xdks/python/reference/xdk.general#submodules)
    * [xdk.general.client module](/xdks/python/reference/xdk.general.client)
      * [`GeneralClient`](/xdks/python/reference/xdk.general.client#xdk.general.client.GeneralClient)
    * [xdk.general.models module](/xdks/python/reference/xdk.general.models)
      * [`GetOpenApiSpecResponse`](/xdks/python/reference/xdk.general.models#xdk.general.models.GetOpenApiSpecResponse)
  * [Module contents](/xdks/python/reference/xdk.general#module-xdk.general)
    * [`GeneralClient`](/xdks/python/reference/xdk.general#xdk.general.GeneralClient)
      * [`GeneralClient.__init__()`](/xdks/python/reference/xdk.general#xdk.general.GeneralClient.__init__)
      * [`GeneralClient.get_open_api_spec()`](/xdks/python/reference/xdk.general#xdk.general.GeneralClient.get_open_api_spec)
* [xdk.lists package](/xdks/python/reference/xdk.lists)
  * [Submodules](/xdks/python/reference/xdk.lists#submodules)
    * [xdk.lists.client module](/xdks/python/reference/xdk.lists.client)
      * [`ListsClient`](/xdks/python/reference/xdk.lists.client#xdk.lists.client.ListsClient)
    * [xdk.lists.models module](/xdks/python/reference/xdk.lists.models)
      * [`AddMemberRequest`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.AddMemberRequest)
      * [`AddMemberResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.AddMemberResponse)
      * [`CreateRequest`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.CreateRequest)
      * [`CreateResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.CreateResponse)
      * [`DeleteResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.DeleteResponse)
      * [`GetByIdResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.GetByIdResponse)
      * [`GetFollowersResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.GetFollowersResponse)
      * [`GetMembersResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.GetMembersResponse)
      * [`GetPostsResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.GetPostsResponse)
      * [`RemoveMemberByUserIdResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.RemoveMemberByUserIdResponse)
      * [`UpdateRequest`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.UpdateRequest)
      * [`UpdateResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.UpdateResponse)
  * [Module contents](/xdks/python/reference/xdk.lists#module-xdk.lists)
    * [`ListsClient`](/xdks/python/reference/xdk.lists#xdk.lists.ListsClient)
      * [`ListsClient.__init__()`](/xdks/python/reference/xdk.lists#xdk.lists.ListsClient.__init__)
      * [`ListsClient.add_member()`](/xdks/python/reference/xdk.lists#xdk.lists.ListsClient.add_member)
      * [`ListsClient.create()`](/xdks/python/reference/xdk.lists#xdk.lists.ListsClient.create)
      * [`ListsClient.delete()`](/xdks/python/reference/xdk.lists#xdk.lists.ListsClient.delete)
      * [`ListsClient.get_by_id()`](/xdks/python/reference/xdk.lists#xdk.lists.ListsClient.get_by_id)
      * [`ListsClient.get_followers()`](/xdks/python/reference/xdk.lists#xdk.lists.ListsClient.get_followers)
      * [`ListsClient.get_members()`](/xdks/python/reference/xdk.lists#xdk.lists.ListsClient.get_members)
      * [`ListsClient.get_posts()`](/xdks/python/reference/xdk.lists#xdk.lists.ListsClient.get_posts)
      * [`ListsClient.remove_member_by_user_id()`](/xdks/python/reference/xdk.lists#xdk.lists.ListsClient.remove_member_by_user_id)
      * [`ListsClient.update()`](/xdks/python/reference/xdk.lists#xdk.lists.ListsClient.update)
* [xdk.media package](/xdks/python/reference/xdk.media)
  * [Submodules](/xdks/python/reference/xdk.media#submodules)
    * [xdk.media.client module](/xdks/python/reference/xdk.media.client)
      * [`MediaClient`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient)
    * [xdk.media.models module](/xdks/python/reference/xdk.media.models)
      * [`AppendUploadRequest`](/xdks/python/reference/xdk.media.models#xdk.media.models.AppendUploadRequest)
      * [`AppendUploadResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.AppendUploadResponse)
      * [`CreateMetadataRequest`](/xdks/python/reference/xdk.media.models#xdk.media.models.CreateMetadataRequest)
      * [`CreateMetadataResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.CreateMetadataResponse)
      * [`CreateSubtitlesRequest`](/xdks/python/reference/xdk.media.models#xdk.media.models.CreateSubtitlesRequest)
      * [`CreateSubtitlesResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.CreateSubtitlesResponse)
      * [`DeleteSubtitlesRequest`](/xdks/python/reference/xdk.media.models#xdk.media.models.DeleteSubtitlesRequest)
      * [`DeleteSubtitlesResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.DeleteSubtitlesResponse)
      * [`FinalizeUploadResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.FinalizeUploadResponse)
      * [`GetAnalyticsResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.GetAnalyticsResponse)
      * [`GetByKeyResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.GetByKeyResponse)
      * [`GetByKeysResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.GetByKeysResponse)
      * [`GetUploadStatusResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.GetUploadStatusResponse)
      * [`InitializeUploadRequest`](/xdks/python/reference/xdk.media.models#xdk.media.models.InitializeUploadRequest)
      * [`InitializeUploadResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.InitializeUploadResponse)
      * [`UploadRequest`](/xdks/python/reference/xdk.media.models#xdk.media.models.UploadRequest)
      * [`UploadResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.UploadResponse)
  * [Module contents](/xdks/python/reference/xdk.media#module-xdk.media)
    * [`MediaClient`](/xdks/python/reference/xdk.media#xdk.media.MediaClient)
      * [`MediaClient.__init__()`](/xdks/python/reference/xdk.media#xdk.media.MediaClient.__init__)
      * [`MediaClient.append_upload()`](/xdks/python/reference/xdk.media#xdk.media.MediaClient.append_upload)
      * [`MediaClient.create_metadata()`](/xdks/python/reference/xdk.media#xdk.media.MediaClient.create_metadata)
      * [`MediaClient.create_subtitles()`](/xdks/python/reference/xdk.media#xdk.media.MediaClient.create_subtitles)
      * [`MediaClient.delete_subtitles()`](/xdks/python/reference/xdk.media#xdk.media.MediaClient.delete_subtitles)
      * [`MediaClient.finalize_upload()`](/xdks/python/reference/xdk.media#xdk.media.MediaClient.finalize_upload)
      * [`MediaClient.get_analytics()`](/xdks/python/reference/xdk.media#xdk.media.MediaClient.get_analytics)
      * [`MediaClient.get_by_key()`](/xdks/python/reference/xdk.media#xdk.media.MediaClient.get_by_key)
      * [`MediaClient.get_by_keys()`](/xdks/python/reference/xdk.media#xdk.media.MediaClient.get_by_keys)
      * [`MediaClient.get_upload_status()`](/xdks/python/reference/xdk.media#xdk.media.MediaClient.get_upload_status)
      * [`MediaClient.initialize_upload()`](/xdks/python/reference/xdk.media#xdk.media.MediaClient.initialize_upload)
      * [`MediaClient.upload()`](/xdks/python/reference/xdk.media#xdk.media.MediaClient.upload)
* [xdk.news package](/xdks/python/reference/xdk.news)
  * [Submodules](/xdks/python/reference/xdk.news#submodules)
    * [xdk.news.client module](/xdks/python/reference/xdk.news.client)
      * [`NewsClient`](/xdks/python/reference/xdk.news.client#xdk.news.client.NewsClient)
    * [xdk.news.models module](/xdks/python/reference/xdk.news.models)
      * [`GetResponse`](/xdks/python/reference/xdk.news.models#xdk.news.models.GetResponse)
      * [`SearchResponse`](/xdks/python/reference/xdk.news.models#xdk.news.models.SearchResponse)
  * [Module contents](/xdks/python/reference/xdk.news#module-xdk.news)
    * [`NewsClient`](/xdks/python/reference/xdk.news#xdk.news.NewsClient)
      * [`NewsClient.__init__()`](/xdks/python/reference/xdk.news#xdk.news.NewsClient.__init__)
      * [`NewsClient.get()`](/xdks/python/reference/xdk.news#xdk.news.NewsClient.get)
      * [`NewsClient.search()`](/xdks/python/reference/xdk.news#xdk.news.NewsClient.search)
* [xdk.posts package](/xdks/python/reference/xdk.posts)
  * [Submodules](/xdks/python/reference/xdk.posts#submodules)
    * [xdk.posts.client module](/xdks/python/reference/xdk.posts.client)
      * [`PostsClient`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient)
    * [xdk.posts.models module](/xdks/python/reference/xdk.posts.models)
      * [`CreateRequest`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.CreateRequest)
      * [`CreateResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.CreateResponse)
      * [`DeleteResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.DeleteResponse)
      * [`GetAnalyticsResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetAnalyticsResponse)
      * [`GetByIdResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetByIdResponse)
      * [`GetByIdsResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetByIdsResponse)
      * [`GetCountsAllResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetCountsAllResponse)
      * [`GetCountsRecentResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetCountsRecentResponse)
      * [`GetInsights28hrResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetInsights28hrResponse)
      * [`GetInsightsHistoricalResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetInsightsHistoricalResponse)
      * [`GetLikingUsersResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetLikingUsersResponse)
      * [`GetQuotedResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetQuotedResponse)
      * [`GetRepostedByResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetRepostedByResponse)
      * [`GetRepostsResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetRepostsResponse)
      * [`HideReplyRequest`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.HideReplyRequest)
      * [`HideReplyResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.HideReplyResponse)
      * [`SearchAllResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.SearchAllResponse)
      * [`SearchRecentResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.SearchRecentResponse)
  * [Module contents](/xdks/python/reference/xdk.posts#module-xdk.posts)
    * [`PostsClient`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient)
      * [`PostsClient.__init__()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.__init__)
      * [`PostsClient.create()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.create)
      * [`PostsClient.delete()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.delete)
      * [`PostsClient.get_analytics()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.get_analytics)
      * [`PostsClient.get_by_id()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.get_by_id)
      * [`PostsClient.get_by_ids()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.get_by_ids)
      * [`PostsClient.get_counts_all()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.get_counts_all)
      * [`PostsClient.get_counts_recent()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.get_counts_recent)
      * [`PostsClient.get_insights28hr()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.get_insights28hr)
      * [`PostsClient.get_insights_historical()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.get_insights_historical)
      * [`PostsClient.get_liking_users()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.get_liking_users)
      * [`PostsClient.get_quoted()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.get_quoted)
      * [`PostsClient.get_reposted_by()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.get_reposted_by)
      * [`PostsClient.get_reposts()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.get_reposts)
      * [`PostsClient.hide_reply()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.hide_reply)
      * [`PostsClient.search_all()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.search_all)
      * [`PostsClient.search_recent()`](/xdks/python/reference/xdk.posts#xdk.posts.PostsClient.search_recent)
* [xdk.spaces package](/xdks/python/reference/xdk.spaces)
  * [Submodules](/xdks/python/reference/xdk.spaces#submodules)
    * [xdk.spaces.client module](/xdks/python/reference/xdk.spaces.client)
      * [`SpacesClient`](/xdks/python/reference/xdk.spaces.client#xdk.spaces.client.SpacesClient)
    * [xdk.spaces.models module](/xdks/python/reference/xdk.spaces.models)
      * [`GetBuyersResponse`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetBuyersResponse)
      * [`GetByCreatorIdsResponse`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetByCreatorIdsResponse)
      * [`GetByIdResponse`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetByIdResponse)
      * [`GetByIdsResponse`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetByIdsResponse)
      * [`GetPostsResponse`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetPostsResponse)
      * [`SearchResponse`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.SearchResponse)
  * [Module contents](/xdks/python/reference/xdk.spaces#module-xdk.spaces)
    * [`SpacesClient`](/xdks/python/reference/xdk.spaces#xdk.spaces.SpacesClient)
      * [`SpacesClient.__init__()`](/xdks/python/reference/xdk.spaces#xdk.spaces.SpacesClient.__init__)
      * [`SpacesClient.get_buyers()`](/xdks/python/reference/xdk.spaces#xdk.spaces.SpacesClient.get_buyers)
      * [`SpacesClient.get_by_creator_ids()`](/xdks/python/reference/xdk.spaces#xdk.spaces.SpacesClient.get_by_creator_ids)
      * [`SpacesClient.get_by_id()`](/xdks/python/reference/xdk.spaces#xdk.spaces.SpacesClient.get_by_id)
      * [`SpacesClient.get_by_ids()`](/xdks/python/reference/xdk.spaces#xdk.spaces.SpacesClient.get_by_ids)
      * [`SpacesClient.get_posts()`](/xdks/python/reference/xdk.spaces#xdk.spaces.SpacesClient.get_posts)
      * [`SpacesClient.search()`](/xdks/python/reference/xdk.spaces#xdk.spaces.SpacesClient.search)
* [xdk.stream package](/xdks/python/reference/xdk.stream)
  * [Submodules](/xdks/python/reference/xdk.stream#submodules)
    * [xdk.stream.client module](/xdks/python/reference/xdk.stream.client)
      * [`StreamClient`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient)
    * [xdk.stream.models module](/xdks/python/reference/xdk.stream.models)
      * [`GetRuleCountsResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.GetRuleCountsResponse)
      * [`GetRulesResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.GetRulesResponse)
      * [`LabelsComplianceResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.LabelsComplianceResponse)
      * [`LikesComplianceResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.LikesComplianceResponse)
      * [`LikesFirehoseResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.LikesFirehoseResponse)
      * [`LikesSample10Response`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.LikesSample10Response)
      * [`PostsComplianceResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsComplianceResponse)
      * [`PostsFirehoseEnResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehoseEnResponse)
      * [`PostsFirehoseJaResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehoseJaResponse)
      * [`PostsFirehoseKoResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehoseKoResponse)
      * [`PostsFirehosePtResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehosePtResponse)
      * [`PostsFirehoseResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehoseResponse)
      * [`PostsResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsResponse)
      * [`PostsSample10Response`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsSample10Response)
      * [`PostsSampleResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsSampleResponse)
      * [`UpdateRulesRequest`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.UpdateRulesRequest)
      * [`UpdateRulesResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.UpdateRulesResponse)
      * [`UsersComplianceResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.UsersComplianceResponse)
  * [Module contents](/xdks/python/reference/xdk.stream#module-xdk.stream)
    * [`StreamClient`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient)
      * [`StreamClient.__init__()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.__init__)
      * [`StreamClient.get_rule_counts()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.get_rule_counts)
      * [`StreamClient.get_rules()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.get_rules)
      * [`StreamClient.labels_compliance()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.labels_compliance)
      * [`StreamClient.likes_compliance()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.likes_compliance)
      * [`StreamClient.likes_firehose()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.likes_firehose)
      * [`StreamClient.likes_sample10()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.likes_sample10)
      * [`StreamClient.posts()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.posts)
      * [`StreamClient.posts_compliance()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.posts_compliance)
      * [`StreamClient.posts_firehose()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.posts_firehose)
      * [`StreamClient.posts_firehose_en()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.posts_firehose_en)
      * [`StreamClient.posts_firehose_ja()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.posts_firehose_ja)
      * [`StreamClient.posts_firehose_ko()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.posts_firehose_ko)
      * [`StreamClient.posts_firehose_pt()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.posts_firehose_pt)
      * [`StreamClient.posts_sample()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.posts_sample)
      * [`StreamClient.posts_sample10()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.posts_sample10)
      * [`StreamClient.update_rules()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.update_rules)
      * [`StreamClient.users_compliance()`](/xdks/python/reference/xdk.stream#xdk.stream.StreamClient.users_compliance)
* [xdk.trends package](/xdks/python/reference/xdk.trends)
  * [Submodules](/xdks/python/reference/xdk.trends#submodules)
    * [xdk.trends.client module](/xdks/python/reference/xdk.trends.client)
      * [`TrendsClient`](/xdks/python/reference/xdk.trends.client#xdk.trends.client.TrendsClient)
    * [xdk.trends.models module](/xdks/python/reference/xdk.trends.models)
      * [`GetAiResponse`](/xdks/python/reference/xdk.trends.models#xdk.trends.models.GetAiResponse)
      * [`GetByWoeidResponse`](/xdks/python/reference/xdk.trends.models#xdk.trends.models.GetByWoeidResponse)
      * [`GetPersonalizedResponse`](/xdks/python/reference/xdk.trends.models#xdk.trends.models.GetPersonalizedResponse)
  * [Module contents](/xdks/python/reference/xdk.trends#module-xdk.trends)
    * [`TrendsClient`](/xdks/python/reference/xdk.trends#xdk.trends.TrendsClient)
      * [`TrendsClient.__init__()`](/xdks/python/reference/xdk.trends#xdk.trends.TrendsClient.__init__)
      * [`TrendsClient.get_ai()`](/xdks/python/reference/xdk.trends#xdk.trends.TrendsClient.get_ai)
      * [`TrendsClient.get_by_woeid()`](/xdks/python/reference/xdk.trends#xdk.trends.TrendsClient.get_by_woeid)
      * [`TrendsClient.get_personalized()`](/xdks/python/reference/xdk.trends#xdk.trends.TrendsClient.get_personalized)
* [xdk.usage package](/xdks/python/reference/xdk.usage)
  * [Submodules](/xdks/python/reference/xdk.usage#submodules)
    * [xdk.usage.client module](/xdks/python/reference/xdk.usage.client)
      * [`UsageClient`](/xdks/python/reference/xdk.usage.client#xdk.usage.client.UsageClient)
    * [xdk.usage.models module](/xdks/python/reference/xdk.usage.models)
      * [`GetResponse`](/xdks/python/reference/xdk.usage.models#xdk.usage.models.GetResponse)
  * [Module contents](/xdks/python/reference/xdk.usage#module-xdk.usage)
    * [`UsageClient`](/xdks/python/reference/xdk.usage#xdk.usage.UsageClient)
      * [`UsageClient.__init__()`](/xdks/python/reference/xdk.usage#xdk.usage.UsageClient.__init__)
      * [`UsageClient.get()`](/xdks/python/reference/xdk.usage#xdk.usage.UsageClient.get)
* [xdk.users package](/xdks/python/reference/xdk.users)
  * [Submodules](/xdks/python/reference/xdk.users#submodules)
    * [xdk.users.client module](/xdks/python/reference/xdk.users.client)
      * [`UsersClient`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient)
    * [xdk.users.models module](/xdks/python/reference/xdk.users.models)
      * [`BlockDmsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.BlockDmsResponse)
      * [`CreateBookmarkRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.CreateBookmarkRequest)
      * [`CreateBookmarkResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.CreateBookmarkResponse)
      * [`DeleteBookmarkResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.DeleteBookmarkResponse)
      * [`FollowListRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.FollowListRequest)
      * [`FollowListResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.FollowListResponse)
      * [`FollowUserRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.FollowUserRequest)
      * [`FollowUserResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.FollowUserResponse)
      * [`GetBlockingResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetBlockingResponse)
      * [`GetBookmarkFoldersResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetBookmarkFoldersResponse)
      * [`GetBookmarksByFolderIdResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetBookmarksByFolderIdResponse)
      * [`GetBookmarksResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetBookmarksResponse)
      * [`GetByIdResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetByIdResponse)
      * [`GetByIdsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetByIdsResponse)
      * [`GetByUsernameResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetByUsernameResponse)
      * [`GetByUsernamesResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetByUsernamesResponse)
      * [`GetFollowedListsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetFollowedListsResponse)
      * [`GetFollowersResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetFollowersResponse)
      * [`GetFollowingResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetFollowingResponse)
      * [`GetLikedPostsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetLikedPostsResponse)
      * [`GetListMembershipsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetListMembershipsResponse)
      * [`GetMeResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetMeResponse)
      * [`GetMentionsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetMentionsResponse)
      * [`GetMutingResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetMutingResponse)
      * [`GetOwnedListsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetOwnedListsResponse)
      * [`GetPinnedListsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetPinnedListsResponse)
      * [`GetPostsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetPostsResponse)
      * [`GetRepostsOfMeResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetRepostsOfMeResponse)
      * [`GetTimelineResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetTimelineResponse)
      * [`LikePostRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.LikePostRequest)
      * [`LikePostResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.LikePostResponse)
      * [`MuteUserRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.MuteUserRequest)
      * [`MuteUserResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.MuteUserResponse)
      * [`PinListRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.PinListRequest)
      * [`PinListResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.PinListResponse)
      * [`RepostPostRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.RepostPostRequest)
      * [`RepostPostResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.RepostPostResponse)
      * [`SearchResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.SearchResponse)
      * [`UnblockDmsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnblockDmsResponse)
      * [`UnfollowListResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnfollowListResponse)
      * [`UnfollowUserResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnfollowUserResponse)
      * [`UnlikePostResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnlikePostResponse)
      * [`UnmuteUserResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnmuteUserResponse)
      * [`UnpinListResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnpinListResponse)
      * [`UnrepostPostResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnrepostPostResponse)
  * [Module contents](/xdks/python/reference/xdk.users#module-xdk.users)
    * [`UsersClient`](/xdks/python/reference/xdk.users#xdk.users.UsersClient)
      * [`UsersClient.__init__()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.__init__)
      * [`UsersClient.block_dms()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.block_dms)
      * [`UsersClient.create_bookmark()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.create_bookmark)
      * [`UsersClient.delete_bookmark()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.delete_bookmark)
      * [`UsersClient.follow_list()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.follow_list)
      * [`UsersClient.follow_user()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.follow_user)
      * [`UsersClient.get_blocking()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_blocking)
      * [`UsersClient.get_bookmark_folders()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_bookmark_folders)
      * [`UsersClient.get_bookmarks()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_bookmarks)
      * [`UsersClient.get_bookmarks_by_folder_id()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_bookmarks_by_folder_id)
      * [`UsersClient.get_by_id()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_by_id)
      * [`UsersClient.get_by_ids()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_by_ids)
      * [`UsersClient.get_by_username()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_by_username)
      * [`UsersClient.get_by_usernames()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_by_usernames)
      * [`UsersClient.get_followed_lists()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_followed_lists)
      * [`UsersClient.get_followers()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_followers)
      * [`UsersClient.get_following()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_following)
      * [`UsersClient.get_liked_posts()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_liked_posts)
      * [`UsersClient.get_list_memberships()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_list_memberships)
      * [`UsersClient.get_me()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_me)
      * [`UsersClient.get_mentions()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_mentions)
      * [`UsersClient.get_muting()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_muting)
      * [`UsersClient.get_owned_lists()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_owned_lists)
      * [`UsersClient.get_pinned_lists()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_pinned_lists)
      * [`UsersClient.get_posts()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_posts)
      * [`UsersClient.get_reposts_of_me()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_reposts_of_me)
      * [`UsersClient.get_timeline()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.get_timeline)
      * [`UsersClient.like_post()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.like_post)
      * [`UsersClient.mute_user()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.mute_user)
      * [`UsersClient.pin_list()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.pin_list)
      * [`UsersClient.repost_post()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.repost_post)
      * [`UsersClient.search()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.search)
      * [`UsersClient.unblock_dms()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.unblock_dms)
      * [`UsersClient.unfollow_list()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.unfollow_list)
      * [`UsersClient.unfollow_user()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.unfollow_user)
      * [`UsersClient.unlike_post()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.unlike_post)
      * [`UsersClient.unmute_user()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.unmute_user)
      * [`UsersClient.unpin_list()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.unpin_list)
      * [`UsersClient.unrepost_post()`](/xdks/python/reference/xdk.users#xdk.users.UsersClient.unrepost_post)
* [xdk.webhooks package](/xdks/python/reference/xdk.webhooks)
  * [Submodules](/xdks/python/reference/xdk.webhooks#submodules)
    * [xdk.webhooks.client module](/xdks/python/reference/xdk.webhooks.client)
      * [`WebhooksClient`](/xdks/python/reference/xdk.webhooks.client#xdk.webhooks.client.WebhooksClient)
    * [xdk.webhooks.models module](/xdks/python/reference/xdk.webhooks.models)
      * [`CreateRequest`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateRequest)
      * [`CreateResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateResponse)
      * [`CreateStreamLinkResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateStreamLinkResponse)
      * [`CreateWebhookReplayJobRequest`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateWebhookReplayJobRequest)
      * [`CreateWebhookReplayJobResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateWebhookReplayJobResponse)
      * [`DeleteResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.DeleteResponse)
      * [`DeleteStreamLinkResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.DeleteStreamLinkResponse)
      * [`GetResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.GetResponse)
      * [`GetStreamLinksResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.GetStreamLinksResponse)
      * [`ValidateResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.ValidateResponse)
  * [Module contents](/xdks/python/reference/xdk.webhooks#module-xdk.webhooks)
    * [`WebhooksClient`](/xdks/python/reference/xdk.webhooks#xdk.webhooks.WebhooksClient)
      * [`WebhooksClient.__init__()`](/xdks/python/reference/xdk.webhooks#xdk.webhooks.WebhooksClient.__init__)
      * [`WebhooksClient.create()`](/xdks/python/reference/xdk.webhooks#xdk.webhooks.WebhooksClient.create)
      * [`WebhooksClient.create_stream_link()`](/xdks/python/reference/xdk.webhooks#xdk.webhooks.WebhooksClient.create_stream_link)
      * [`WebhooksClient.create_webhook_replay_job()`](/xdks/python/reference/xdk.webhooks#xdk.webhooks.WebhooksClient.create_webhook_replay_job)
      * [`WebhooksClient.delete()`](/xdks/python/reference/xdk.webhooks#xdk.webhooks.WebhooksClient.delete)
      * [`WebhooksClient.delete_stream_link()`](/xdks/python/reference/xdk.webhooks#xdk.webhooks.WebhooksClient.delete_stream_link)
      * [`WebhooksClient.get()`](/xdks/python/reference/xdk.webhooks#xdk.webhooks.WebhooksClient.get)
      * [`WebhooksClient.get_stream_links()`](/xdks/python/reference/xdk.webhooks#xdk.webhooks.WebhooksClient.get_stream_links)
      * [`WebhooksClient.validate()`](/xdks/python/reference/xdk.webhooks#xdk.webhooks.WebhooksClient.validate)

## Submodules

* [xdk.client module](/xdks/python/reference/xdk.client)
  * [`Client`](/xdks/python/reference/xdk.client#xdk.client.Client)
    * [`Client.__init__()`](/xdks/python/reference/xdk.client#xdk.client.Client.__init__)
    * [`Client.access_token`](/xdks/python/reference/xdk.client#xdk.client.Client.access_token)
    * [`Client.exchange_code()`](/xdks/python/reference/xdk.client#xdk.client.Client.exchange_code)
    * [`Client.fetch_token()`](/xdks/python/reference/xdk.client#xdk.client.Client.fetch_token)
    * [`Client.get_authorization_url()`](/xdks/python/reference/xdk.client#xdk.client.Client.get_authorization_url)
    * [`Client.is_token_expired()`](/xdks/python/reference/xdk.client#xdk.client.Client.is_token_expired)
    * [`Client.oauth2_session`](/xdks/python/reference/xdk.client#xdk.client.Client.oauth2_session)
    * [`Client.refresh_token()`](/xdks/python/reference/xdk.client#xdk.client.Client.refresh_token)
    * [`Client.token`](/xdks/python/reference/xdk.client#xdk.client.Client.token)
* [xdk.oauth1\_auth module](/xdks/python/reference/xdk.oauth1_auth)
  * [`OAuth1`](/xdks/python/reference/xdk.oauth1_auth#xdk.oauth1_auth.OAuth1)
    * [`OAuth1.__init__()`](/xdks/python/reference/xdk.oauth1_auth#xdk.oauth1_auth.OAuth1.__init__)
    * [`OAuth1.build_request_header()`](/xdks/python/reference/xdk.oauth1_auth#xdk.oauth1_auth.OAuth1.build_request_header)
    * [`OAuth1.get_access_token()`](/xdks/python/reference/xdk.oauth1_auth#xdk.oauth1_auth.OAuth1.get_access_token)
    * [`OAuth1.get_authorization_url()`](/xdks/python/reference/xdk.oauth1_auth#xdk.oauth1_auth.OAuth1.get_authorization_url)
    * [`OAuth1.get_request_token()`](/xdks/python/reference/xdk.oauth1_auth#xdk.oauth1_auth.OAuth1.get_request_token)
    * [`OAuth1.start_oauth_flow()`](/xdks/python/reference/xdk.oauth1_auth#xdk.oauth1_auth.OAuth1.start_oauth_flow)
  * [`OAuth1AccessToken`](/xdks/python/reference/xdk.oauth1_auth#xdk.oauth1_auth.OAuth1AccessToken)
    * [`OAuth1AccessToken.__init__()`](/xdks/python/reference/xdk.oauth1_auth#xdk.oauth1_auth.OAuth1AccessToken.__init__)
  * [`OAuth1RequestToken`](/xdks/python/reference/xdk.oauth1_auth#xdk.oauth1_auth.OAuth1RequestToken)
    * [`OAuth1RequestToken.__init__()`](/xdks/python/reference/xdk.oauth1_auth#xdk.oauth1_auth.OAuth1RequestToken.__init__)
* [xdk.oauth2\_auth module](/xdks/python/reference/xdk.oauth2_auth)
  * [`OAuth2PKCEAuth`](/xdks/python/reference/xdk.oauth2_auth#xdk.oauth2_auth.OAuth2PKCEAuth)
    * [`OAuth2PKCEAuth.__init__()`](/xdks/python/reference/xdk.oauth2_auth#xdk.oauth2_auth.OAuth2PKCEAuth.__init__)
    * [`OAuth2PKCEAuth.access_token`](/xdks/python/reference/xdk.oauth2_auth#xdk.oauth2_auth.OAuth2PKCEAuth.access_token)
    * [`OAuth2PKCEAuth.exchange_code()`](/xdks/python/reference/xdk.oauth2_auth#xdk.oauth2_auth.OAuth2PKCEAuth.exchange_code)
    * [`OAuth2PKCEAuth.fetch_token()`](/xdks/python/reference/xdk.oauth2_auth#xdk.oauth2_auth.OAuth2PKCEAuth.fetch_token)
    * [`OAuth2PKCEAuth.get_authorization_url()`](/xdks/python/reference/xdk.oauth2_auth#xdk.oauth2_auth.OAuth2PKCEAuth.get_authorization_url)
    * [`OAuth2PKCEAuth.get_code_challenge()`](/xdks/python/reference/xdk.oauth2_auth#xdk.oauth2_auth.OAuth2PKCEAuth.get_code_challenge)
    * [`OAuth2PKCEAuth.get_code_verifier()`](/xdks/python/reference/xdk.oauth2_auth#xdk.oauth2_auth.OAuth2PKCEAuth.get_code_verifier)
    * [`OAuth2PKCEAuth.is_token_expired()`](/xdks/python/reference/xdk.oauth2_auth#xdk.oauth2_auth.OAuth2PKCEAuth.is_token_expired)
    * [`OAuth2PKCEAuth.refresh_token()`](/xdks/python/reference/xdk.oauth2_auth#xdk.oauth2_auth.OAuth2PKCEAuth.refresh_token)
    * [`OAuth2PKCEAuth.set_pkce_parameters()`](/xdks/python/reference/xdk.oauth2_auth#xdk.oauth2_auth.OAuth2PKCEAuth.set_pkce_parameters)
* [xdk.paginator module](/xdks/python/reference/xdk.paginator)
  * [`Cursor`](/xdks/python/reference/xdk.paginator#xdk.paginator.Cursor)
    * [`Cursor.__init__()`](/xdks/python/reference/xdk.paginator#xdk.paginator.Cursor.__init__)
    * [`Cursor.items()`](/xdks/python/reference/xdk.paginator#xdk.paginator.Cursor.items)
    * [`Cursor.pages()`](/xdks/python/reference/xdk.paginator#xdk.paginator.Cursor.pages)
  * [`PaginatableMethod`](/xdks/python/reference/xdk.paginator#xdk.paginator.PaginatableMethod)
    * [`PaginatableMethod.__init__()`](/xdks/python/reference/xdk.paginator#xdk.paginator.PaginatableMethod.__init__)
  * [`PaginationError`](/xdks/python/reference/xdk.paginator#xdk.paginator.PaginationError)
  * [`cursor()`](/xdks/python/reference/xdk.paginator#xdk.paginator.cursor)
* [xdk.streaming module](/xdks/python/reference/xdk.streaming)
  * [`StreamConfig`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig)
    * [`StreamConfig.max_retries`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig.max_retries)
    * [`StreamConfig.initial_backoff`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig.initial_backoff)
    * [`StreamConfig.max_backoff`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig.max_backoff)
    * [`StreamConfig.backoff_multiplier`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig.backoff_multiplier)
    * [`StreamConfig.jitter`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig.jitter)
    * [`StreamConfig.timeout`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig.timeout)
    * [`StreamConfig.chunk_size`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig.chunk_size)
    * [`StreamConfig.on_connect`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig.on_connect)
    * [`StreamConfig.on_disconnect`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig.on_disconnect)
    * [`StreamConfig.on_reconnect`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig.on_reconnect)
    * [`StreamConfig.on_error`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig.on_error)
    * [`StreamConfig.__init__()`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamConfig.__init__)
    * [`StreamConfig.backoff_multiplier`](/xdks/python/reference/xdk.streaming#id0)
    * [`StreamConfig.chunk_size`](/xdks/python/reference/xdk.streaming#id1)
    * [`StreamConfig.initial_backoff`](/xdks/python/reference/xdk.streaming#id2)
    * [`StreamConfig.jitter`](/xdks/python/reference/xdk.streaming#id3)
    * [`StreamConfig.max_backoff`](/xdks/python/reference/xdk.streaming#id4)
    * [`StreamConfig.max_retries`](/xdks/python/reference/xdk.streaming#id5)
    * [`StreamConfig.on_connect`](/xdks/python/reference/xdk.streaming#id6)
    * [`StreamConfig.on_disconnect`](/xdks/python/reference/xdk.streaming#id7)
    * [`StreamConfig.on_error`](/xdks/python/reference/xdk.streaming#id8)
    * [`StreamConfig.on_reconnect`](/xdks/python/reference/xdk.streaming#id9)
    * [`StreamConfig.timeout`](/xdks/python/reference/xdk.streaming#id10)
  * [`StreamError`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamError)
    * [`StreamError.__init__()`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamError.__init__)
    * [`StreamError.is_retryable`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamError.is_retryable)
  * [`StreamErrorType`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamErrorType)
    * [`StreamErrorType.AUTHENTICATION_ERROR`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamErrorType.AUTHENTICATION_ERROR)
    * [`StreamErrorType.CLIENT_ERROR`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamErrorType.CLIENT_ERROR)
    * [`StreamErrorType.CONNECTION_ERROR`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamErrorType.CONNECTION_ERROR)
    * [`StreamErrorType.FATAL_ERROR`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamErrorType.FATAL_ERROR)
    * [`StreamErrorType.RATE_LIMITED`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamErrorType.RATE_LIMITED)
    * [`StreamErrorType.SERVER_ERROR`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamErrorType.SERVER_ERROR)
    * [`StreamErrorType.STREAM_INTERRUPTED`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamErrorType.STREAM_INTERRUPTED)
    * [`StreamErrorType.TIMEOUT`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamErrorType.TIMEOUT)
  * [`StreamState`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamState)
    * [`StreamState.__init__()`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamState.__init__)
    * [`StreamState.current_backoff`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamState.current_backoff)
    * [`StreamState.is_connected`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamState.is_connected)
    * [`StreamState.last_error`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamState.last_error)
    * [`StreamState.retry_count`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamState.retry_count)
    * [`StreamState.total_items_received`](/xdks/python/reference/xdk.streaming#xdk.streaming.StreamState.total_items_received)
  * [`stream_with_retry()`](/xdks/python/reference/xdk.streaming#xdk.streaming.stream_with_retry)

## Module contents

XDK Python SDK.

A Python SDK for the X API that provides convenient access
to the X API endpoints with type safety and authentication support.

### `class xdk.Client`

Client for interacting with the X API.

#### Parameters

<ParamField type="str" />

<ParamField type="str or None" />

<ParamField type="str or None" />

<ParamField type="str or None" />

<ParamField type="str or None" />

<ParamField type="str or None" />

<ParamField type="Dict[str, Any] or None" />

<ParamField type="str or List[str] or None" />

<ParamField type="str" />

<ParamField type="OAuth1" />

### `__init__`

Initialize the X API client.

#### Parameters

<ParamField type="str">
  The base URL for the X API (defaults to [https://api.x.com](https://api.x.com)).
</ParamField>

<ParamField type="str or None">
  The bearer token for the X API (app-only authentication).
</ParamField>

<ParamField type="str or None">
  The OAuth2 access token for user context (can be used directly as bearer token).
</ParamField>

<ParamField type="str or None">
  The client ID for the X API (required for OAuth2 PKCE flow).
</ParamField>

<ParamField type="str or None">
  The client secret for the X API.
</ParamField>

<ParamField type="str or None">
  The redirect URI for OAuth2 authorization.
</ParamField>

<ParamField type="Dict[str, Any] or None">
  An existing OAuth2 token dictionary (if available). If provided, access\_token will be extracted.
</ParamField>

<ParamField type="str or List[str] or None">
  Space-separated string or list of strings for OAuth2 authorization scopes.
</ParamField>

<ParamField type="str">
  The base URL for OAuth2 authorization (defaults to [https://x.com/i](https://x.com/i)).
</ParamField>

<ParamField type="OAuth1">
  OAuth1 instance for OAuth1.0a authentication.
</ParamField>

### `exchange_code`

Exchange authorization code for tokens (matches TypeScript API).

#### Parameters

<ParamField type="Any">
  The authorization code from the callback.
</ParamField>

<ParamField type="Any">
  Optional code verifier (uses stored verifier if not provided).
</ParamField>

### `fetch_token`

Fetch token using authorization response URL (legacy method).

#### Parameters

<ParamField type="Any">
  The full callback URL received after authorization.
</ParamField>

### `get_authorization_url`

Get the authorization URL for the OAuth2 PKCE flow.

#### Parameters

<ParamField type="Any">
  Optional state parameter for security.
</ParamField>

### `is_token_expired`

Check if the OAuth2 token is expired.

### `refresh_token`

Refresh the OAuth2 token.

### `class xdk.Cursor`

\[`ResponseType`]

#### Parameters

<ParamField type="PaginatableMethod" />

### `__init__`

Initialize the cursor.

#### Parameters

<ParamField type="PaginatableMethod">
  The API method to call for each page (must support pagination)
</ParamField>

### `items`

Iterate over individual items from paginated responses.

#### Parameters

<ParamField type="int or None">
  Maximum number of items to return (None for unlimited)
</ParamField>

#### Returns

`IteratorAny`

### `pages`

Iterate over pages of responses.

#### Parameters

<ParamField type="int or None">
  Maximum number of pages to return (None for unlimited)
</ParamField>

#### Returns

`IteratorResponseType`

### `class xdk.StreamConfig`

Configuration for streaming connections with retry behavior.

#### Parameters

<ParamField type="int" />

<ParamField type="float" />

<ParamField type="float" />

<ParamField type="float" />

<ParamField type="bool" />

<ParamField type="float or None" />

<ParamField type="int" />

<ParamField type="Callable[[], None] or None" />

<ParamField type="Callable[[Exception or None], None] or None" />

<ParamField type="Callable[[int, float], None] or None" />

<ParamField type="Callable[[[StreamError" />

### `__init__`

#### Parameters

<ParamField type="int" />

<ParamField type="float" />

<ParamField type="float" />

<ParamField type="float" />

<ParamField type="bool" />

<ParamField type="float or None" />

<ParamField type="int" />

<ParamField type="Callable[[], None] or None" />

<ParamField type="Callable[[Exception or None], None] or None" />

<ParamField type="Callable[[int, float], None] or None" />

<ParamField type="Callable[[[StreamError" />

### `on_error : Callable[[[StreamError]`

### `exception xdk.StreamError`

Exception raised for streaming errors with classification.

#### Parameters

<ParamField type="str" />

<ParamField type="StreamErrorType" />

### `__init__`

#### Parameters

<ParamField type="str" />

<ParamField type="StreamErrorType" />

### `class xdk.StreamErrorType`

Classification of streaming errors for retry decisions.

#### Parameters

<ParamField type="Any" />

### `class xdk.StreamState`

Internal state for a streaming connection.

#### Parameters

<ParamField type="int" />

<ParamField type="float" />

<ParamField type="bool" />

<ParamField type="int" />

<ParamField type="StreamError" />

### `__init__`

#### Parameters

<ParamField type="int" />

<ParamField type="float" />

<ParamField type="bool" />

<ParamField type="int" />

<ParamField type="StreamError" />

### `last_error : [StreamError]`

### `xdk.cursor`

Create a cursor with proper type inference and validation.
This factory function helps with type inference so you get proper
type hints for the response type, and validates that the method
supports pagination at both static analysis and runtime.

#### Parameters

<ParamField type="PaginatableMethod">
  The API method to wrap (must support pagination)
</ParamField>


# AccountActivityClient
Source: https://docs.x.com/xdks/python/reference/xdk.account_activity

Reference for the account_activity Python package in the X API SDK, grouping the client and Pydantic models for the account activity endpoints of the X API.

## Submodules

* [xdk.account\_activity.client module](/xdks/python/reference/xdk.account_activity.client)
  * [`AccountActivityClient`](/xdks/python/reference/xdk.account_activity.client#xdk.account_activity.client.AccountActivityClient)
    * [`AccountActivityClient.__init__()`](/xdks/python/reference/xdk.account_activity.client#xdk.account_activity.client.AccountActivityClient.__init__)
    * [`AccountActivityClient.create_replay_job()`](/xdks/python/reference/xdk.account_activity.client#xdk.account_activity.client.AccountActivityClient.create_replay_job)
    * [`AccountActivityClient.create_subscription()`](/xdks/python/reference/xdk.account_activity.client#xdk.account_activity.client.AccountActivityClient.create_subscription)
    * [`AccountActivityClient.delete_subscription()`](/xdks/python/reference/xdk.account_activity.client#xdk.account_activity.client.AccountActivityClient.delete_subscription)
    * [`AccountActivityClient.get_subscription_count()`](/xdks/python/reference/xdk.account_activity.client#xdk.account_activity.client.AccountActivityClient.get_subscription_count)
    * [`AccountActivityClient.get_subscriptions()`](/xdks/python/reference/xdk.account_activity.client#xdk.account_activity.client.AccountActivityClient.get_subscriptions)
    * [`AccountActivityClient.validate_subscription()`](/xdks/python/reference/xdk.account_activity.client#xdk.account_activity.client.AccountActivityClient.validate_subscription)
* [xdk.account\_activity.models module](/xdks/python/reference/xdk.account_activity.models)
  * [`CreateReplayJobResponse`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.CreateReplayJobResponse)
    * [`CreateReplayJobResponse.model_config`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.CreateReplayJobResponse.model_config)
  * [`CreateSubscriptionRequest`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.CreateSubscriptionRequest)
    * [`CreateSubscriptionRequest.model_config`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.CreateSubscriptionRequest.model_config)
  * [`CreateSubscriptionResponse`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.CreateSubscriptionResponse)
    * [`CreateSubscriptionResponse.model_config`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.CreateSubscriptionResponse.model_config)
  * [`DeleteSubscriptionResponse`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.DeleteSubscriptionResponse)
    * [`DeleteSubscriptionResponse.model_config`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.DeleteSubscriptionResponse.model_config)
  * [`GetSubscriptionCountResponse`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.GetSubscriptionCountResponse)
    * [`GetSubscriptionCountResponse.model_config`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.GetSubscriptionCountResponse.model_config)
  * [`GetSubscriptionsResponse`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.GetSubscriptionsResponse)
    * [`GetSubscriptionsResponse.model_config`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.GetSubscriptionsResponse.model_config)
  * [`ValidateSubscriptionResponse`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.ValidateSubscriptionResponse)
    * [`ValidateSubscriptionResponse.model_config`](/xdks/python/reference/xdk.account_activity.models#xdk.account_activity.models.ValidateSubscriptionResponse.model_config)

## Module contents

This module provides access to the account activity endpoints of the X API
and serves as the main entry point for all account activity-related functionality.

### `class xdk.account_activity.AccountActivityClient`

Client for account activity operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create_replay_job`

Create replay job
Creates a replay job to retrieve activities from up to the past 5 days for all subscriptions associated with a given webhook.

#### Parameters

<ParamField type="Any">
  The unique identifier for the webhook configuration.
</ParamField>

<ParamField type="str">
  The oldest (starting) UTC timestamp (inclusive) from which events will be provided, in yyyymmddhhmm format.
</ParamField>

<ParamField type="str">
  The latest (ending) UTC timestamp (exclusive) up to which events will be provided, in yyyymmddhhmm format.
</ParamField>

#### Returns

`CreateReplayJobResponse` - Response data

### `create_subscription`

Create subscription
Creates an Account Activity subscription for the user and the given webhook.

#### Parameters

<ParamField type="Any">
  The webhook ID to check subscription against.
</ParamField>

<ParamField type="CreateSubscriptionRequest">
  Request body
</ParamField>

### `delete_subscription`

Delete subscription
Deletes an Account Activity subscription for the given webhook and user ID.

#### Parameters

<ParamField type="Any">
  The webhook ID to check subscription against.
</ParamField>

<ParamField type="Any">
  User ID to unsubscribe from.
</ParamField>

#### Returns

`DeleteSubscriptionResponse` - Response data

### `get_subscription_count`

Get subscription count
Retrieves a count of currently active Account Activity subscriptions.
:returns: Response data
:rtype: GetSubscriptionCountResponse

#### Returns

`GetSubscriptionCountResponse`

### `get_subscriptions`

Get subscriptions
Retrieves a list of all active subscriptions for a given webhook.

#### Parameters

<ParamField type="Any">
  The webhook ID to pull subscriptions for.
</ParamField>

#### Returns

`GetSubscriptionsResponse` - Response data

### `validate_subscription`

Validate subscription
Checks a user’s Account Activity subscription for a given webhook.

#### Parameters

<ParamField type="Any">
  The webhook ID to check subscription against.
</ParamField>

#### Returns

`ValidateSubscriptionResponse` - Response data


# AccountActivityClient
Source: https://docs.x.com/xdks/python/reference/xdk.account_activity.client

Reference for the account_activity.client Python module in the X API SDK. Client class and methods for calling the account activity endpoints of the X API v2.

## AccountActivityClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for account activity operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create_replay_job`

Create replay job
Creates a replay job to retrieve activities from up to the past 5 days for all subscriptions associated with a given webhook.

#### Parameters

<ParamField type="Any">
  The unique identifier for the webhook configuration.
</ParamField>

<ParamField type="str">
  The oldest (starting) UTC timestamp (inclusive) from which events will be provided, in yyyymmddhhmm format.
</ParamField>

<ParamField type="str">
  The latest (ending) UTC timestamp (exclusive) up to which events will be provided, in yyyymmddhhmm format.
</ParamField>

#### Returns

`CreateReplayJobResponse` - Response data

### `create_subscription`

Create subscription
Creates an Account Activity subscription for the user and the given webhook.

#### Parameters

<ParamField type="Any">
  The webhook ID to check subscription against.
</ParamField>

<ParamField type="CreateSubscriptionRequest">
  Request body
</ParamField>

### `delete_subscription`

Delete subscription
Deletes an Account Activity subscription for the given webhook and user ID.

#### Parameters

<ParamField type="Any">
  The webhook ID to check subscription against.
</ParamField>

<ParamField type="Any">
  User ID to unsubscribe from.
</ParamField>

#### Returns

`DeleteSubscriptionResponse` - Response data

### `get_subscription_count`

Get subscription count
Retrieves a count of currently active Account Activity subscriptions.
:returns: Response data
:rtype: GetSubscriptionCountResponse

#### Returns

`GetSubscriptionCountResponse`

### `get_subscriptions`

Get subscriptions
Retrieves a list of all active subscriptions for a given webhook.

#### Parameters

<ParamField type="Any">
  The webhook ID to pull subscriptions for.
</ParamField>

#### Returns

`GetSubscriptionsResponse` - Response data

### `validate_subscription`

Validate subscription
Checks a user’s Account Activity subscription for a given webhook.

#### Parameters

<ParamField type="Any">
  The webhook ID to check subscription against.
</ParamField>

#### Returns

`ValidateSubscriptionResponse` - Response data


# Account_activity.Models
Source: https://docs.x.com/xdks/python/reference/xdk.account_activity.models

Reference for the Python XDK account_activity.models module, listing Pydantic response classes for replay jobs, subscriptions, and subscription counts.

This module provides Pydantic models for request and response data structures
for the account activity endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

## CreateReplayJobResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for create\_replay\_job

## Methods

### `class xdk.account_activity.models.CreateReplayJobResponse`

Response model for create\_replay\_job

### `class xdk.account_activity.models.CreateSubscriptionResponse`

Response model for create\_subscription

### `class xdk.account_activity.models.DeleteSubscriptionResponse`

Response model for delete\_subscription

### `class xdk.account_activity.models.GetSubscriptionCountResponse`

Response model for get\_subscription\_count

### `class xdk.account_activity.models.GetSubscriptionsResponse`

Response model for get\_subscriptions

### `class xdk.account_activity.models.ValidateSubscriptionResponse`

Response model for validate\_subscription


# ActivityClient
Source: https://docs.x.com/xdks/python/reference/xdk.activity

Reference for the activity Python package in the X API SDK, grouping the client and Pydantic models for the activity endpoints of the X API v2.

## Submodules

* [xdk.activity.client module](/xdks/python/reference/xdk.activity.client)
  * [`ActivityClient`](/xdks/python/reference/xdk.activity.client#xdk.activity.client.ActivityClient)
    * [`ActivityClient.__init__()`](/xdks/python/reference/xdk.activity.client#xdk.activity.client.ActivityClient.__init__)
    * [`ActivityClient.create_subscription()`](/xdks/python/reference/xdk.activity.client#xdk.activity.client.ActivityClient.create_subscription)
    * [`ActivityClient.delete_subscription()`](/xdks/python/reference/xdk.activity.client#xdk.activity.client.ActivityClient.delete_subscription)
    * [`ActivityClient.get_subscriptions()`](/xdks/python/reference/xdk.activity.client#xdk.activity.client.ActivityClient.get_subscriptions)
    * [`ActivityClient.stream()`](/xdks/python/reference/xdk.activity.client#xdk.activity.client.ActivityClient.stream)
    * [`ActivityClient.update_subscription()`](/xdks/python/reference/xdk.activity.client#xdk.activity.client.ActivityClient.update_subscription)
* [xdk.activity.models module](/xdks/python/reference/xdk.activity.models)
  * [`CreateSubscriptionRequest`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.CreateSubscriptionRequest)
    * [`CreateSubscriptionRequest.model_config`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.CreateSubscriptionRequest.model_config)
  * [`CreateSubscriptionResponse`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.CreateSubscriptionResponse)
    * [`CreateSubscriptionResponse.model_config`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.CreateSubscriptionResponse.model_config)
  * [`DeleteSubscriptionResponse`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.DeleteSubscriptionResponse)
    * [`DeleteSubscriptionResponse.model_config`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.DeleteSubscriptionResponse.model_config)
  * [`GetSubscriptionsResponse`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.GetSubscriptionsResponse)
    * [`GetSubscriptionsResponse.model_config`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.GetSubscriptionsResponse.model_config)
  * [`StreamResponse`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.StreamResponse)
    * [`StreamResponse.model_config`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.StreamResponse.model_config)
  * [`UpdateSubscriptionRequest`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.UpdateSubscriptionRequest)
    * [`UpdateSubscriptionRequest.model_config`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.UpdateSubscriptionRequest.model_config)
  * [`UpdateSubscriptionResponse`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.UpdateSubscriptionResponse)
    * [`UpdateSubscriptionResponse.model_config`](/xdks/python/reference/xdk.activity.models#xdk.activity.models.UpdateSubscriptionResponse.model_config)

## Module contents

This module provides access to the activity endpoints of the X API
and serves as the main entry point for all activity-related functionality.

### `class xdk.activity.ActivityClient`

Streaming Client for activity operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create_subscription`

Create X activity subscription
Creates a subscription for an X activity event
body: Request body
:returns: Response data
:rtype: CreateSubscriptionResponse

#### Parameters

<ParamField type="CreateSubscriptionRequest" />

### `delete_subscription`

Deletes X activity subscription
Deletes a subscription for an X activity event

#### Parameters

<ParamField type="Any">
  The ID of the subscription to delete.
</ParamField>

#### Returns

`DeleteSubscriptionResponse` - Response data

### `get_subscriptions`

Get X activity subscriptions
Get a list of active subscriptions for XAA
:returns: Response data
:rtype: GetSubscriptionsResponse

#### Returns

`GetSubscriptionsResponse`

### `stream`

Activity Stream (Streaming)
Stream of X Activities
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Post labels will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp from which the Post labels will be provided.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `update_subscription`

Update X activity subscription
Updates a subscription for an X activity event

#### Parameters

<ParamField type="Any">
  The ID of the subscription to update.
</ParamField>

<ParamField type="UpdateSubscriptionRequest">
  Request body
</ParamField>


# ActivityClient
Source: https://docs.x.com/xdks/python/reference/xdk.activity.client

Reference for the activity.client Python module in the X API SDK. Client class and methods for calling the activity endpoints of the X API v2.

This module provides a client for interacting with the activity endpoints of the X API.
Real-time streaming operations return generators that yield data as it arrives.
Streaming connections are automatically managed with exponential backoff retry logic for robust handling.

## ActivityClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Streaming Client for activity operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create_subscription`

Create X activity subscription
Creates a subscription for an X activity event
body: Request body
:returns: Response data
:rtype: CreateSubscriptionResponse

#### Parameters

<ParamField type="CreateSubscriptionRequest" />

### `delete_subscription`

Deletes X activity subscription
Deletes a subscription for an X activity event

#### Parameters

<ParamField type="Any">
  The ID of the subscription to delete.
</ParamField>

#### Returns

`DeleteSubscriptionResponse` - Response data

### `get_subscriptions`

Get X activity subscriptions
Get a list of active subscriptions for XAA
:returns: Response data
:rtype: GetSubscriptionsResponse

#### Returns

`GetSubscriptionsResponse`

### `stream`

Activity Stream (Streaming)
Stream of X Activities
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Post labels will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp from which the Post labels will be provided.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `update_subscription`

Update X activity subscription
Updates a subscription for an X activity event

#### Parameters

<ParamField type="Any">
  The ID of the subscription to update.
</ParamField>

<ParamField type="UpdateSubscriptionRequest">
  Request body
</ParamField>


# Activity.Models
Source: https://docs.x.com/xdks/python/reference/xdk.activity.models

Reference for the activity.models Python module in the X API SDK. Pydantic request and response models for the activity endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the activity endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

### class xdk.activity.models.CreateSubscriptionRequest

Request model for create\_subscription

<ResponseField name="model_config" type="ConfigDict">
  Default: `{'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}`

  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
</ResponseField>

## CreateSubscriptionResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for create\_subscription

## Methods

### `class xdk.activity.models.CreateSubscriptionResponse`

Response model for create\_subscription

### `class xdk.activity.models.DeleteSubscriptionResponse`

Response model for delete\_subscription

### `class xdk.activity.models.GetSubscriptionsResponse`

Response model for get\_subscriptions

### `class xdk.activity.models.StreamResponse`

Response model for stream

### `class xdk.activity.models.UpdateSubscriptionResponse`

Response model for update\_subscription


# Client
Source: https://docs.x.com/xdks/python/reference/xdk.client

Reference for the client Python package in the X API SDK, grouping the client and Pydantic models for the client endpoints of the X API v2.

This module provides the primary Client class for interacting with the X API.
It coordinates all sub-clients and handles authentication, session management,
and OAuth2 PKCE flows. All functionality is generated from the OpenAPI specification.

## Client

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

\| None = None)

Client for interacting with the X API.

## Constructors

### `__init__`

Initialize the X API client.

#### Parameters

<ParamField type="str">
  The base URL for the X API (defaults to [https://api.x.com](https://api.x.com)).
</ParamField>

<ParamField type="str or None">
  The bearer token for the X API (app-only authentication).
</ParamField>

<ParamField type="str or None">
  The OAuth2 access token for user context (can be used directly as bearer token).
</ParamField>

<ParamField type="str or None">
  The client ID for the X API (required for OAuth2 PKCE flow).
</ParamField>

<ParamField type="str or None">
  The client secret for the X API.
</ParamField>

<ParamField type="str or None">
  The redirect URI for OAuth2 authorization.
</ParamField>

<ParamField type="Dict[str, Any] or None">
  An existing OAuth2 token dictionary (if available). If provided, access\_token will be extracted.
</ParamField>

<ParamField type="str or List[str] or None">
  Space-separated string or list of strings for OAuth2 authorization scopes.
</ParamField>

<ParamField type="str">
  The base URL for OAuth2 authorization (defaults to [https://x.com/i](https://x.com/i)).
</ParamField>

<ParamField type="OAuth1">
  OAuth1 instance for OAuth1.0a authentication.
</ParamField>

#### Parameters

<ParamField type="str" />

<ParamField type="str or None" />

<ParamField type="str or None" />

<ParamField type="str or None" />

<ParamField type="str or None" />

<ParamField type="str or None" />

<ParamField type="Dict[str, Any] or None" />

<ParamField type="str or List[str] or None" />

<ParamField type="str" />

<ParamField type="OAuth1" />

### `exchange_code`

Exchange authorization code for tokens (matches TypeScript API).

#### Parameters

<ParamField type="Any">
  The authorization code from the callback.
</ParamField>

<ParamField type="Any">
  Optional code verifier (uses stored verifier if not provided).
</ParamField>

### `fetch_token`

Fetch token using authorization response URL (legacy method).

#### Parameters

<ParamField type="Any">
  The full callback URL received after authorization.
</ParamField>

### `get_authorization_url`

Get the authorization URL for the OAuth2 PKCE flow.

#### Parameters

<ParamField type="Any">
  Optional state parameter for security.
</ParamField>

### `is_token_expired`

Check if the OAuth2 token is expired.

### `refresh_token`

Refresh the OAuth2 token.


# CommunitiesClient
Source: https://docs.x.com/xdks/python/reference/xdk.communities

Reference for the communities Python package in the X API SDK, grouping the client and Pydantic models for the communities endpoints of the X API v2.

## Submodules

* [xdk.communities.client module](/xdks/python/reference/xdk.communities.client)
  * [`CommunitiesClient`](/xdks/python/reference/xdk.communities.client#xdk.communities.client.CommunitiesClient)
    * [`CommunitiesClient.__init__()`](/xdks/python/reference/xdk.communities.client#xdk.communities.client.CommunitiesClient.__init__)
    * [`CommunitiesClient.get_by_id()`](/xdks/python/reference/xdk.communities.client#xdk.communities.client.CommunitiesClient.get_by_id)
    * [`CommunitiesClient.search()`](/xdks/python/reference/xdk.communities.client#xdk.communities.client.CommunitiesClient.search)
* [xdk.communities.models module](/xdks/python/reference/xdk.communities.models)
  * [`GetByIdResponse`](/xdks/python/reference/xdk.communities.models#xdk.communities.models.GetByIdResponse)
    * [`GetByIdResponse.model_config`](/xdks/python/reference/xdk.communities.models#xdk.communities.models.GetByIdResponse.model_config)
  * [`SearchResponse`](/xdks/python/reference/xdk.communities.models#xdk.communities.models.SearchResponse)
    * [`SearchResponse.model_config`](/xdks/python/reference/xdk.communities.models#xdk.communities.models.SearchResponse.model_config)

## Module contents

This module provides access to the communities endpoints of the X API
and serves as the main entry point for all communities-related functionality.

### `class xdk.communities.CommunitiesClient`

Client for communities operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get_by_id`

Get Community by ID
Retrieves details of a specific Community by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the Community.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Community fields to display.
</ParamField>

#### Returns

`GetByIdResponse` - Response data

### `search`

Search Communities
Retrieves a list of Communities matching the specified search query.

#### Parameters

<ParamField type="str">
  Query to search communities.
</ParamField>

<ParamField type="int or None">
  The maximum number of search results to be returned by a request.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Community fields to display.
</ParamField>

#### Returns

`IteratorSearchResponse`


# CommunitiesClient
Source: https://docs.x.com/xdks/python/reference/xdk.communities.client

Reference for the communities.client Python module in the X API SDK. Client class and methods for calling the communities endpoints of the X API v2.

## CommunitiesClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for communities operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get_by_id`

Get Community by ID
Retrieves details of a specific Community by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the Community.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Community fields to display.
</ParamField>

#### Returns

`GetByIdResponse` - Response data

### `search`

Search Communities
Retrieves a list of Communities matching the specified search query.

#### Parameters

<ParamField type="str">
  Query to search communities.
</ParamField>

<ParamField type="int or None">
  The maximum number of search results to be returned by a request.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Community fields to display.
</ParamField>

#### Returns

`IteratorSearchResponse`


# Communities.Models
Source: https://docs.x.com/xdks/python/reference/xdk.communities.models

Reference for the communities.models Python module in the X API SDK. Pydantic request and response models for the communities endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the communities endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

## GetByIdResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for get\_by\_id

## Methods

### `class xdk.communities.models.GetByIdResponse`

Response model for get\_by\_id

### `class xdk.communities.models.SearchResponse`

Response model for search


# CommunityNotesClient
Source: https://docs.x.com/xdks/python/reference/xdk.community_notes

Reference for the community_notes Python package in the X API SDK, grouping the client and Pydantic models for the community notes endpoints of the X API v2.

## Submodules

* [xdk.community\_notes.client module](/xdks/python/reference/xdk.community_notes.client)
  * [`CommunityNotesClient`](/xdks/python/reference/xdk.community_notes.client#xdk.community_notes.client.CommunityNotesClient)
    * [`CommunityNotesClient.__init__()`](/xdks/python/reference/xdk.community_notes.client#xdk.community_notes.client.CommunityNotesClient.__init__)
    * [`CommunityNotesClient.create()`](/xdks/python/reference/xdk.community_notes.client#xdk.community_notes.client.CommunityNotesClient.create)
    * [`CommunityNotesClient.delete()`](/xdks/python/reference/xdk.community_notes.client#xdk.community_notes.client.CommunityNotesClient.delete)
    * [`CommunityNotesClient.evaluate()`](/xdks/python/reference/xdk.community_notes.client#xdk.community_notes.client.CommunityNotesClient.evaluate)
    * [`CommunityNotesClient.search_eligible_posts()`](/xdks/python/reference/xdk.community_notes.client#xdk.community_notes.client.CommunityNotesClient.search_eligible_posts)
    * [`CommunityNotesClient.search_written()`](/xdks/python/reference/xdk.community_notes.client#xdk.community_notes.client.CommunityNotesClient.search_written)
* [xdk.community\_notes.models module](/xdks/python/reference/xdk.community_notes.models)
  * [`CreateRequest`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.CreateRequest)
    * [`CreateRequest.model_config`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.CreateRequest.model_config)
  * [`CreateResponse`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.CreateResponse)
    * [`CreateResponse.model_config`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.CreateResponse.model_config)
  * [`DeleteResponse`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.DeleteResponse)
    * [`DeleteResponse.model_config`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.DeleteResponse.model_config)
  * [`EvaluateRequest`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.EvaluateRequest)
    * [`EvaluateRequest.model_config`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.EvaluateRequest.model_config)
  * [`EvaluateResponse`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.EvaluateResponse)
    * [`EvaluateResponse.model_config`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.EvaluateResponse.model_config)
  * [`SearchEligiblePostsResponse`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.SearchEligiblePostsResponse)
    * [`SearchEligiblePostsResponse.model_config`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.SearchEligiblePostsResponse.model_config)
  * [`SearchWrittenResponse`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.SearchWrittenResponse)
    * [`SearchWrittenResponse.model_config`](/xdks/python/reference/xdk.community_notes.models#xdk.community_notes.models.SearchWrittenResponse.model_config)

## Module contents

This module provides access to the community notes endpoints of the X API
and serves as the main entry point for all community notes-related functionality.

### `class xdk.community_notes.CommunityNotesClient`

Client for community notes operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create`

Create a Community Note
Creates a community note endpoint for LLM use case.
body: Request body
:returns: Response data
:rtype: CreateResponse

#### Parameters

<ParamField type="CreateRequest" />

### `delete`

Delete a Community Note
Deletes a community note.

#### Parameters

<ParamField type="Any">
  The community note id to delete.
</ParamField>

#### Returns

`DeleteResponse` - Response data

### `evaluate`

Evaluate a Community Note
Endpoint to evaluate a community note.
body: Request body
:returns: Response data
:rtype: EvaluateResponse

#### Parameters

<ParamField type="EvaluateRequest" />

### `search_eligible_posts`

Search for Posts Eligible for Community Notes
Returns all the posts that are eligible for community notes.

#### Parameters

<ParamField type="bool">
  If true, return a list of posts that are for the test. If false, return a list of posts that the bots can write proposed notes on the product.
</ParamField>

<ParamField type="str or None">
  Pagination token to get next set of posts eligible for notes.
</ParamField>

<ParamField type="int or None">
  Max results to return.
</ParamField>

<ParamField type="str or None">
  The selection of posts to return. Valid values are ‘feed\_size: small’ and ‘feed\_size: large’. Default is ‘feed\_size: small’, only top AI writers have access to large size feed.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorSearchEligiblePostsResponse`

### `search_written`

Search for Community Notes Written
Returns all the community notes written by the user.

#### Parameters

<ParamField type="bool">
  If true, return the notes the caller wrote for the test. If false, return the notes the caller wrote on the product.
</ParamField>

<ParamField type="str or None">
  Pagination token to get next set of posts eligible for notes.
</ParamField>

<ParamField type="int or None">
  Max results to return.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Note fields to display.
</ParamField>

#### Returns

`IteratorSearchWrittenResponse`


# CommunityNotesClient
Source: https://docs.x.com/xdks/python/reference/xdk.community_notes.client

Reference for the community_notes.client Python module in the X API SDK. Client class and methods for calling the community notes endpoints of the X API v2.

## CommunityNotesClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for community notes operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create`

Create a Community Note
Creates a community note endpoint for LLM use case.
body: Request body
:returns: Response data
:rtype: CreateResponse

#### Parameters

<ParamField type="CreateRequest" />

### `delete`

Delete a Community Note
Deletes a community note.

#### Parameters

<ParamField type="Any">
  The community note id to delete.
</ParamField>

#### Returns

`DeleteResponse` - Response data

### `evaluate`

Evaluate a Community Note
Endpoint to evaluate a community note.
body: Request body
:returns: Response data
:rtype: EvaluateResponse

#### Parameters

<ParamField type="EvaluateRequest" />

### `search_eligible_posts`

Search for Posts Eligible for Community Notes
Returns all the posts that are eligible for community notes.

#### Parameters

<ParamField type="bool">
  If true, return a list of posts that are for the test. If false, return a list of posts that the bots can write proposed notes on the product.
</ParamField>

<ParamField type="str or None">
  Pagination token to get next set of posts eligible for notes.
</ParamField>

<ParamField type="int or None">
  Max results to return.
</ParamField>

<ParamField type="str or None">
  The selection of posts to return. Valid values are ‘feed\_size: small’ and ‘feed\_size: large’. Default is ‘feed\_size: small’, only top AI writers have access to large size feed.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorSearchEligiblePostsResponse`

### `search_written`

Search for Community Notes Written
Returns all the community notes written by the user.

#### Parameters

<ParamField type="bool">
  If true, return the notes the caller wrote for the test. If false, return the notes the caller wrote on the product.
</ParamField>

<ParamField type="str or None">
  Pagination token to get next set of posts eligible for notes.
</ParamField>

<ParamField type="int or None">
  Max results to return.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Note fields to display.
</ParamField>

#### Returns

`IteratorSearchWrittenResponse`


# Community_notes.Models
Source: https://docs.x.com/xdks/python/reference/xdk.community_notes.models

Reference for the community_notes.models Python module in the X API SDK. Pydantic request and response models for the community notes endpoints of the X API.

This module provides Pydantic models for request and response data structures
for the community notes endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

### class xdk.community\_notes.models.CreateRequest

Request model for create

<ResponseField name="model_config" type="ConfigDict">
  Default: `{'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}`

  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
</ResponseField>

## CreateResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for create

## Methods

### `class xdk.community_notes.models.CreateResponse`

Response model for create

### `class xdk.community_notes.models.DeleteResponse`

Response model for delete

### `class xdk.community_notes.models.EvaluateResponse`

Response model for evaluate

### `class xdk.community_notes.models.SearchEligiblePostsResponse`

Response model for search\_eligible\_posts

### `class xdk.community_notes.models.SearchWrittenResponse`

Response model for search\_written


# ComplianceClient
Source: https://docs.x.com/xdks/python/reference/xdk.compliance

Reference for the compliance Python package in the X API SDK, grouping the client and Pydantic models for the compliance endpoints of the X API v2.

## Submodules

* [xdk.compliance.client module](/xdks/python/reference/xdk.compliance.client)
  * [`ComplianceClient`](/xdks/python/reference/xdk.compliance.client#xdk.compliance.client.ComplianceClient)
    * [`ComplianceClient.__init__()`](/xdks/python/reference/xdk.compliance.client#xdk.compliance.client.ComplianceClient.__init__)
    * [`ComplianceClient.create_jobs()`](/xdks/python/reference/xdk.compliance.client#xdk.compliance.client.ComplianceClient.create_jobs)
    * [`ComplianceClient.get_jobs()`](/xdks/python/reference/xdk.compliance.client#xdk.compliance.client.ComplianceClient.get_jobs)
    * [`ComplianceClient.get_jobs_by_id()`](/xdks/python/reference/xdk.compliance.client#xdk.compliance.client.ComplianceClient.get_jobs_by_id)
* [xdk.compliance.models module](/xdks/python/reference/xdk.compliance.models)
  * [`CreateJobsRequest`](/xdks/python/reference/xdk.compliance.models#xdk.compliance.models.CreateJobsRequest)
    * [`CreateJobsRequest.model_config`](/xdks/python/reference/xdk.compliance.models#xdk.compliance.models.CreateJobsRequest.model_config)
  * [`CreateJobsResponse`](/xdks/python/reference/xdk.compliance.models#xdk.compliance.models.CreateJobsResponse)
    * [`CreateJobsResponse.model_config`](/xdks/python/reference/xdk.compliance.models#xdk.compliance.models.CreateJobsResponse.model_config)
  * [`GetJobsByIdResponse`](/xdks/python/reference/xdk.compliance.models#xdk.compliance.models.GetJobsByIdResponse)
    * [`GetJobsByIdResponse.model_config`](/xdks/python/reference/xdk.compliance.models#xdk.compliance.models.GetJobsByIdResponse.model_config)
  * [`GetJobsResponse`](/xdks/python/reference/xdk.compliance.models#xdk.compliance.models.GetJobsResponse)
    * [`GetJobsResponse.model_config`](/xdks/python/reference/xdk.compliance.models#xdk.compliance.models.GetJobsResponse.model_config)

## Module contents

This module provides access to the compliance endpoints of the X API
and serves as the main entry point for all compliance-related functionality.

### `class xdk.compliance.ComplianceClient`

Client for compliance operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create_jobs`

Create Compliance Job
Creates a new Compliance Job for the specified job type.
body: Request body
:returns: Response data
:rtype: CreateJobsResponse

#### Parameters

<ParamField type="CreateJobsRequest" />

### `get_jobs`

Get Compliance Jobs
Retrieves a list of Compliance Jobs filtered by job type and optional status.

#### Parameters

<ParamField type="str">
  Type of Compliance Job to list.
</ParamField>

<ParamField type="str or None">
  Status of Compliance Job to list.
</ParamField>

<ParamField type="List or None">
  A comma separated list of ComplianceJob fields to display.
</ParamField>

#### Returns

`GetJobsResponse` - Response data

### `get_jobs_by_id`

Get Compliance Job by ID
Retrieves details of a specific Compliance Job by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the Compliance Job to retrieve.
</ParamField>

<ParamField type="List or None">
  A comma separated list of ComplianceJob fields to display.
</ParamField>

#### Returns

`GetJobsByIdResponse` - Response data


# ComplianceClient
Source: https://docs.x.com/xdks/python/reference/xdk.compliance.client

Reference for the compliance.client Python module in the X API SDK. Client class and methods for calling the compliance endpoints of the X API v2.

## ComplianceClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for compliance operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create_jobs`

Create Compliance Job
Creates a new Compliance Job for the specified job type.
body: Request body
:returns: Response data
:rtype: CreateJobsResponse

#### Parameters

<ParamField type="CreateJobsRequest" />

### `get_jobs`

Get Compliance Jobs
Retrieves a list of Compliance Jobs filtered by job type and optional status.

#### Parameters

<ParamField type="str">
  Type of Compliance Job to list.
</ParamField>

<ParamField type="str or None">
  Status of Compliance Job to list.
</ParamField>

<ParamField type="List or None">
  A comma separated list of ComplianceJob fields to display.
</ParamField>

#### Returns

`GetJobsResponse` - Response data

### `get_jobs_by_id`

Get Compliance Job by ID
Retrieves details of a specific Compliance Job by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the Compliance Job to retrieve.
</ParamField>

<ParamField type="List or None">
  A comma separated list of ComplianceJob fields to display.
</ParamField>

#### Returns

`GetJobsByIdResponse` - Response data


# Compliance.Models
Source: https://docs.x.com/xdks/python/reference/xdk.compliance.models

Reference for the compliance.models Python module in the X API SDK. Pydantic request and response models for the compliance endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the compliance endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

### class xdk.compliance.models.CreateJobsRequest

Request model for create\_jobs

<ResponseField name="model_config" type="ConfigDict">
  Default: `{'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}`

  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
</ResponseField>

## CreateJobsResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for create\_jobs

## Methods

### `class xdk.compliance.models.CreateJobsResponse`

Response model for create\_jobs

### `class xdk.compliance.models.GetJobsByIdResponse`

Response model for get\_jobs\_by\_id

### `class xdk.compliance.models.GetJobsResponse`

Response model for get\_jobs


# ConnectionsClient
Source: https://docs.x.com/xdks/python/reference/xdk.connections

Reference for the connections Python package in the X API SDK, grouping the client and Pydantic models for the connections endpoints of the X API v2.

## Submodules

* [xdk.connections.client module](/xdks/python/reference/xdk.connections.client)
  * [`ConnectionsClient`](/xdks/python/reference/xdk.connections.client#xdk.connections.client.ConnectionsClient)
    * [`ConnectionsClient.__init__()`](/xdks/python/reference/xdk.connections.client#xdk.connections.client.ConnectionsClient.__init__)
    * [`ConnectionsClient.delete_all()`](/xdks/python/reference/xdk.connections.client#xdk.connections.client.ConnectionsClient.delete_all)
* [xdk.connections.models module](/xdks/python/reference/xdk.connections.models)
  * [`DeleteAllResponse`](/xdks/python/reference/xdk.connections.models#xdk.connections.models.DeleteAllResponse)
    * [`DeleteAllResponse.model_config`](/xdks/python/reference/xdk.connections.models#xdk.connections.models.DeleteAllResponse.model_config)

## Module contents

This module provides access to the connections endpoints of the X API
and serves as the main entry point for all connections-related functionality.

### `class xdk.connections.ConnectionsClient`

Client for connections operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `delete_all`

Terminate all connections
Terminates all active streaming connections for the authenticated application.
:returns: Response data
:rtype: DeleteAllResponse

#### Returns

`DeleteAllResponse`


# ConnectionsClient
Source: https://docs.x.com/xdks/python/reference/xdk.connections.client

Reference for the connections.client Python module in the X API SDK. Client class and methods for calling the connections endpoints of the X API v2.

## ConnectionsClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for connections operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `delete_all`

Terminate all connections
Terminates all active streaming connections for the authenticated application.
:returns: Response data
:rtype: DeleteAllResponse

#### Returns

`DeleteAllResponse`


# Connections.Models
Source: https://docs.x.com/xdks/python/reference/xdk.connections.models

Reference for the connections.models Python module in the X API SDK. Pydantic request and response models for the connections endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the connections endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

## DeleteAllResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for delete\_all

## Methods

### `class xdk.connections.models.DeleteAllResponse`

Response model for delete\_all


# DirectMessagesClient
Source: https://docs.x.com/xdks/python/reference/xdk.direct_messages

Reference for the direct_messages Python package in the X API SDK, grouping the client and Pydantic models for the direct messages endpoints of the X API v2.

## Submodules

* [xdk.direct\_messages.client module](/xdks/python/reference/xdk.direct_messages.client)
  * [`DirectMessagesClient`](/xdks/python/reference/xdk.direct_messages.client#xdk.direct_messages.client.DirectMessagesClient)
    * [`DirectMessagesClient.__init__()`](/xdks/python/reference/xdk.direct_messages.client#xdk.direct_messages.client.DirectMessagesClient.__init__)
    * [`DirectMessagesClient.create_by_conversation_id()`](/xdks/python/reference/xdk.direct_messages.client#xdk.direct_messages.client.DirectMessagesClient.create_by_conversation_id)
    * [`DirectMessagesClient.create_by_participant_id()`](/xdks/python/reference/xdk.direct_messages.client#xdk.direct_messages.client.DirectMessagesClient.create_by_participant_id)
    * [`DirectMessagesClient.create_conversation()`](/xdks/python/reference/xdk.direct_messages.client#xdk.direct_messages.client.DirectMessagesClient.create_conversation)
    * [`DirectMessagesClient.delete_events()`](/xdks/python/reference/xdk.direct_messages.client#xdk.direct_messages.client.DirectMessagesClient.delete_events)
    * [`DirectMessagesClient.get_events()`](/xdks/python/reference/xdk.direct_messages.client#xdk.direct_messages.client.DirectMessagesClient.get_events)
    * [`DirectMessagesClient.get_events_by_conversation_id()`](/xdks/python/reference/xdk.direct_messages.client#xdk.direct_messages.client.DirectMessagesClient.get_events_by_conversation_id)
    * [`DirectMessagesClient.get_events_by_id()`](/xdks/python/reference/xdk.direct_messages.client#xdk.direct_messages.client.DirectMessagesClient.get_events_by_id)
    * [`DirectMessagesClient.get_events_by_participant_id()`](/xdks/python/reference/xdk.direct_messages.client#xdk.direct_messages.client.DirectMessagesClient.get_events_by_participant_id)
* [xdk.direct\_messages.models module](/xdks/python/reference/xdk.direct_messages.models)
  * [`CreateByConversationIdRequest`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateByConversationIdRequest)
    * [`CreateByConversationIdRequest.model_config`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateByConversationIdRequest.model_config)
  * [`CreateByConversationIdResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateByConversationIdResponse)
    * [`CreateByConversationIdResponse.model_config`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateByConversationIdResponse.model_config)
  * [`CreateByParticipantIdRequest`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateByParticipantIdRequest)
    * [`CreateByParticipantIdRequest.model_config`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateByParticipantIdRequest.model_config)
  * [`CreateByParticipantIdResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateByParticipantIdResponse)
    * [`CreateByParticipantIdResponse.model_config`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateByParticipantIdResponse.model_config)
  * [`CreateConversationRequest`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateConversationRequest)
    * [`CreateConversationRequest.model_config`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateConversationRequest.model_config)
  * [`CreateConversationResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateConversationResponse)
    * [`CreateConversationResponse.model_config`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.CreateConversationResponse.model_config)
  * [`DeleteEventsResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.DeleteEventsResponse)
    * [`DeleteEventsResponse.model_config`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.DeleteEventsResponse.model_config)
  * [`GetEventsByConversationIdResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.GetEventsByConversationIdResponse)
    * [`GetEventsByConversationIdResponse.model_config`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.GetEventsByConversationIdResponse.model_config)
  * [`GetEventsByIdResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.GetEventsByIdResponse)
    * [`GetEventsByIdResponse.model_config`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.GetEventsByIdResponse.model_config)
  * [`GetEventsByParticipantIdResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.GetEventsByParticipantIdResponse)
    * [`GetEventsByParticipantIdResponse.model_config`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.GetEventsByParticipantIdResponse.model_config)
  * [`GetEventsResponse`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.GetEventsResponse)
    * [`GetEventsResponse.model_config`](/xdks/python/reference/xdk.direct_messages.models#xdk.direct_messages.models.GetEventsResponse.model_config)

## Module contents

This module provides access to the direct messages endpoints of the X API
and serves as the main entry point for all direct messages-related functionality.

### `class xdk.direct_messages.DirectMessagesClient`

Client for direct messages operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create_by_conversation_id`

Create DM message by conversation ID
Sends a new direct message to a specific conversation by its ID.

#### Parameters

<ParamField type="str">
  The DM Conversation ID.
</ParamField>

<ParamField type="CreateByConversationIdRequest">
  Request body
</ParamField>

### `create_by_participant_id`

Create DM message by participant ID
Sends a new direct message to a specific participant by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the recipient user that will receive the DM.
</ParamField>

<ParamField type="CreateByParticipantIdRequest">
  Request body
</ParamField>

### `create_conversation`

Create DM conversation
Initiates a new direct message conversation with specified participants.
body: Request body
:returns: Response data
:rtype: CreateConversationResponse

#### Parameters

<ParamField type="CreateConversationRequest" />

### `delete_events`

Delete DM event
Deletes a specific direct message event by its ID, if owned by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the direct-message event to delete.
</ParamField>

#### Returns

`DeleteEventsResponse` - Response data

### `get_events`

Get DM events
Retrieves a list of recent direct message events across all conversations.

#### Parameters

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  The set of event\_types to include in the results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of DmEvent fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetEventsResponse`

### `get_events_by_conversation_id`

Get DM events for a DM conversation
Retrieves direct message events for a specific conversation.

#### Parameters

<ParamField type="Any">
  The DM conversation ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  The set of event\_types to include in the results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of DmEvent fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetEventsByConversationIdResponse`

### `get_events_by_id`

Get DM event by ID
Retrieves details of a specific direct message event by its ID.

#### Parameters

<ParamField type="Any">
  dm event id.
</ParamField>

<ParamField type="List or None">
  A comma separated list of DmEvent fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`GetEventsByIdResponse` - Response data

### `get_events_by_participant_id`

Get DM events for a DM conversation
Retrieves direct message events for a specific conversation.

#### Parameters

<ParamField type="Any">
  The ID of the participant user for the One to One DM conversation.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  The set of event\_types to include in the results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of DmEvent fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetEventsByParticipantIdResponse`


# DirectMessagesClient
Source: https://docs.x.com/xdks/python/reference/xdk.direct_messages.client

Reference for the direct_messages.client Python module in the X API SDK. Client class and methods for calling the direct messages endpoints of the X API v2.

## DirectMessagesClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for direct messages operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create_by_conversation_id`

Create DM message by conversation ID
Sends a new direct message to a specific conversation by its ID.

#### Parameters

<ParamField type="str">
  The DM Conversation ID.
</ParamField>

<ParamField type="CreateByConversationIdRequest">
  Request body
</ParamField>

### `create_by_participant_id`

Create DM message by participant ID
Sends a new direct message to a specific participant by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the recipient user that will receive the DM.
</ParamField>

<ParamField type="CreateByParticipantIdRequest">
  Request body
</ParamField>

### `create_conversation`

Create DM conversation
Initiates a new direct message conversation with specified participants.
body: Request body
:returns: Response data
:rtype: CreateConversationResponse

#### Parameters

<ParamField type="CreateConversationRequest" />

### `delete_events`

Delete DM event
Deletes a specific direct message event by its ID, if owned by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the direct-message event to delete.
</ParamField>

#### Returns

`DeleteEventsResponse` - Response data

### `get_events`

Get DM events
Retrieves a list of recent direct message events across all conversations.

#### Parameters

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  The set of event\_types to include in the results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of DmEvent fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetEventsResponse`

### `get_events_by_conversation_id`

Get DM events for a DM conversation
Retrieves direct message events for a specific conversation.

#### Parameters

<ParamField type="Any">
  The DM conversation ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  The set of event\_types to include in the results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of DmEvent fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetEventsByConversationIdResponse`

### `get_events_by_id`

Get DM event by ID
Retrieves details of a specific direct message event by its ID.

#### Parameters

<ParamField type="Any">
  dm event id.
</ParamField>

<ParamField type="List or None">
  A comma separated list of DmEvent fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`GetEventsByIdResponse` - Response data

### `get_events_by_participant_id`

Get DM events for a DM conversation
Retrieves direct message events for a specific conversation.

#### Parameters

<ParamField type="Any">
  The ID of the participant user for the One to One DM conversation.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  The set of event\_types to include in the results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of DmEvent fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetEventsByParticipantIdResponse`


# Direct_messages.Models
Source: https://docs.x.com/xdks/python/reference/xdk.direct_messages.models

Reference for the direct_messages.models Python module in the X API SDK. Pydantic request and response models for the direct messages endpoints of the X API.

This module provides Pydantic models for request and response data structures
for the direct messages endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

### class xdk.direct\_messages.models.CreateByConversationIdRequest

Request model for create\_by\_conversation\_id

<ResponseField name="model_config" type="ConfigDict">
  Default: `{'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}`

  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
</ResponseField>

## CreateByConversationIdResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for create\_by\_conversation\_id

## Methods

### `class xdk.direct_messages.models.CreateByConversationIdResponse`

Response model for create\_by\_conversation\_id

### `class xdk.direct_messages.models.CreateByParticipantIdResponse`

Response model for create\_by\_participant\_id

### `class xdk.direct_messages.models.CreateConversationResponse`

Response model for create\_conversation

### `class xdk.direct_messages.models.DeleteEventsResponse`

Response model for delete\_events

### `class xdk.direct_messages.models.GetEventsByConversationIdResponse`

Response model for get\_events\_by\_conversation\_id

### `class xdk.direct_messages.models.GetEventsByIdResponse`

Response model for get\_events\_by\_id

### `class xdk.direct_messages.models.GetEventsByParticipantIdResponse`

Response model for get\_events\_by\_participant\_id

### `class xdk.direct_messages.models.GetEventsResponse`

Response model for get\_events


# GeneralClient
Source: https://docs.x.com/xdks/python/reference/xdk.general

Reference for the general Python package in the X API SDK, grouping the client and Pydantic models for the general endpoints of the X API v2.

## Submodules

* [xdk.general.client module](/xdks/python/reference/xdk.general.client)
  * [`GeneralClient`](/xdks/python/reference/xdk.general.client#xdk.general.client.GeneralClient)
    * [`GeneralClient.__init__()`](/xdks/python/reference/xdk.general.client#xdk.general.client.GeneralClient.__init__)
    * [`GeneralClient.get_open_api_spec()`](/xdks/python/reference/xdk.general.client#xdk.general.client.GeneralClient.get_open_api_spec)
* [xdk.general.models module](/xdks/python/reference/xdk.general.models)
  * [`GetOpenApiSpecResponse`](/xdks/python/reference/xdk.general.models#xdk.general.models.GetOpenApiSpecResponse)
    * [`GetOpenApiSpecResponse.model_config`](/xdks/python/reference/xdk.general.models#xdk.general.models.GetOpenApiSpecResponse.model_config)

## Module contents

This module provides access to the general endpoints of the X API
and serves as the main entry point for all general-related functionality.

### `class xdk.general.GeneralClient`

Client for general operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get_open_api_spec`

Get OpenAPI Spec.
Retrieves the full OpenAPI Specification in JSON format. (See [https://github.com/OAI/OpenAPI-Specification/blob/master/README.md](https://github.com/OAI/OpenAPI-Specification/blob/master/README.md))
:returns: Response data
:rtype: GetOpenApiSpecResponse

#### Returns

`GetOpenApiSpecResponse`


# GeneralClient
Source: https://docs.x.com/xdks/python/reference/xdk.general.client

Reference for the general.client Python module in the X API SDK. Client class and methods for calling the general endpoints of the X API v2.

## GeneralClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for general operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get_open_api_spec`

Get OpenAPI Spec.
Retrieves the full OpenAPI Specification in JSON format. (See [https://github.com/OAI/OpenAPI-Specification/blob/master/README.md](https://github.com/OAI/OpenAPI-Specification/blob/master/README.md))
:returns: Response data
:rtype: GetOpenApiSpecResponse

#### Returns

`GetOpenApiSpecResponse`


# General.Models
Source: https://docs.x.com/xdks/python/reference/xdk.general.models

Reference for the general.models Python module in the X API SDK. Pydantic request and response models for the general endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the general endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

## GetOpenApiSpecResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for get\_open\_api\_spec

## Methods

### `class xdk.general.models.GetOpenApiSpecResponse`

Response model for get\_open\_api\_spec


# ListsClient
Source: https://docs.x.com/xdks/python/reference/xdk.lists

Reference for the lists Python package in the X API SDK, grouping the client and Pydantic models for the lists endpoints of the X API v2.

## Submodules

* [xdk.lists.client module](/xdks/python/reference/xdk.lists.client)
  * [`ListsClient`](/xdks/python/reference/xdk.lists.client#xdk.lists.client.ListsClient)
    * [`ListsClient.__init__()`](/xdks/python/reference/xdk.lists.client#xdk.lists.client.ListsClient.__init__)
    * [`ListsClient.add_member()`](/xdks/python/reference/xdk.lists.client#xdk.lists.client.ListsClient.add_member)
    * [`ListsClient.create()`](/xdks/python/reference/xdk.lists.client#xdk.lists.client.ListsClient.create)
    * [`ListsClient.delete()`](/xdks/python/reference/xdk.lists.client#xdk.lists.client.ListsClient.delete)
    * [`ListsClient.get_by_id()`](/xdks/python/reference/xdk.lists.client#xdk.lists.client.ListsClient.get_by_id)
    * [`ListsClient.get_followers()`](/xdks/python/reference/xdk.lists.client#xdk.lists.client.ListsClient.get_followers)
    * [`ListsClient.get_members()`](/xdks/python/reference/xdk.lists.client#xdk.lists.client.ListsClient.get_members)
    * [`ListsClient.get_posts()`](/xdks/python/reference/xdk.lists.client#xdk.lists.client.ListsClient.get_posts)
    * [`ListsClient.remove_member_by_user_id()`](/xdks/python/reference/xdk.lists.client#xdk.lists.client.ListsClient.remove_member_by_user_id)
    * [`ListsClient.update()`](/xdks/python/reference/xdk.lists.client#xdk.lists.client.ListsClient.update)
* [xdk.lists.models module](/xdks/python/reference/xdk.lists.models)
  * [`AddMemberRequest`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.AddMemberRequest)
    * [`AddMemberRequest.model_config`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.AddMemberRequest.model_config)
  * [`AddMemberResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.AddMemberResponse)
    * [`AddMemberResponse.model_config`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.AddMemberResponse.model_config)
  * [`CreateRequest`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.CreateRequest)
    * [`CreateRequest.model_config`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.CreateRequest.model_config)
  * [`CreateResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.CreateResponse)
    * [`CreateResponse.model_config`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.CreateResponse.model_config)
  * [`DeleteResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.DeleteResponse)
    * [`DeleteResponse.model_config`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.DeleteResponse.model_config)
  * [`GetByIdResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.GetByIdResponse)
    * [`GetByIdResponse.model_config`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.GetByIdResponse.model_config)
  * [`GetFollowersResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.GetFollowersResponse)
    * [`GetFollowersResponse.model_config`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.GetFollowersResponse.model_config)
  * [`GetMembersResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.GetMembersResponse)
    * [`GetMembersResponse.model_config`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.GetMembersResponse.model_config)
  * [`GetPostsResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.GetPostsResponse)
    * [`GetPostsResponse.model_config`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.GetPostsResponse.model_config)
  * [`RemoveMemberByUserIdResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.RemoveMemberByUserIdResponse)
    * [`RemoveMemberByUserIdResponse.model_config`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.RemoveMemberByUserIdResponse.model_config)
  * [`UpdateRequest`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.UpdateRequest)
    * [`UpdateRequest.model_config`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.UpdateRequest.model_config)
  * [`UpdateResponse`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.UpdateResponse)
    * [`UpdateResponse.model_config`](/xdks/python/reference/xdk.lists.models#xdk.lists.models.UpdateResponse.model_config)

## Module contents

This module provides access to the lists endpoints of the X API
and serves as the main entry point for all lists-related functionality.

### `class xdk.lists.ListsClient`

Client for lists operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `add_member`

Add List member
Adds a User to a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List for which to add a member.
</ParamField>

<ParamField type="AddMemberRequest">
  Request body
</ParamField>

### `create`

Create List
Creates a new List for the authenticated user.
body: Request body
:returns: Response data
:rtype: CreateResponse

#### Parameters

<ParamField type="CreateRequest" />

### `delete`

Delete List
Deletes a specific List owned by the authenticated user by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List to delete.
</ParamField>

#### Returns

`DeleteResponse` - Response data

### `get_by_id`

Get List by ID
Retrieves details of a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List.
</ParamField>

<ParamField type="List or None">
  A comma separated list of List fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

#### Returns

`GetByIdResponse` - Response data

### `get_followers`

Get List followers
Retrieves a list of Users who follow a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetFollowersResponse`

### `get_members`

Get List members
Retrieves a list of Users who are members of a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetMembersResponse`

### `get_posts`

Get List Posts
Retrieves a list of Posts associated with a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetPostsResponse`

### `remove_member_by_user_id`

Remove List member
Removes a User from a specific List by its ID and the User’s ID.

#### Parameters

<ParamField type="Any">
  The ID of the List to remove a member.
</ParamField>

<ParamField type="Any">
  The ID of User that will be removed from the List.
</ParamField>

#### Returns

`RemoveMemberByUserIdResponse` - Response data

### `update`

Update List
Updates the details of a specific List owned by the authenticated user by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List to modify.
</ParamField>

<ParamField type="UpdateRequest">
  Request body
</ParamField>


# ListsClient
Source: https://docs.x.com/xdks/python/reference/xdk.lists.client

Reference for the lists.client Python module in the X API SDK. Client class and methods for calling the lists endpoints of the X API v2.

## ListsClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for lists operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `add_member`

Add List member
Adds a User to a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List for which to add a member.
</ParamField>

<ParamField type="AddMemberRequest">
  Request body
</ParamField>

### `create`

Create List
Creates a new List for the authenticated user.
body: Request body
:returns: Response data
:rtype: CreateResponse

#### Parameters

<ParamField type="CreateRequest" />

### `delete`

Delete List
Deletes a specific List owned by the authenticated user by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List to delete.
</ParamField>

#### Returns

`DeleteResponse` - Response data

### `get_by_id`

Get List by ID
Retrieves details of a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List.
</ParamField>

<ParamField type="List or None">
  A comma separated list of List fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

#### Returns

`GetByIdResponse` - Response data

### `get_followers`

Get List followers
Retrieves a list of Users who follow a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetFollowersResponse`

### `get_members`

Get List members
Retrieves a list of Users who are members of a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetMembersResponse`

### `get_posts`

Get List Posts
Retrieves a list of Posts associated with a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetPostsResponse`

### `remove_member_by_user_id`

Remove List member
Removes a User from a specific List by its ID and the User’s ID.

#### Parameters

<ParamField type="Any">
  The ID of the List to remove a member.
</ParamField>

<ParamField type="Any">
  The ID of User that will be removed from the List.
</ParamField>

#### Returns

`RemoveMemberByUserIdResponse` - Response data

### `update`

Update List
Updates the details of a specific List owned by the authenticated user by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the List to modify.
</ParamField>

<ParamField type="UpdateRequest">
  Request body
</ParamField>


# Lists.Models
Source: https://docs.x.com/xdks/python/reference/xdk.lists.models

Reference for the lists.models Python module in the X API SDK. Pydantic request and response models for the lists endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the lists endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

### class xdk.lists.models.AddMemberRequest

Request model for add\_member

<ResponseField name="model_config" type="ConfigDict">
  Default: `{'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}`

  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
</ResponseField>

## AddMemberResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for add\_member

## Methods

### `class xdk.lists.models.AddMemberResponse`

Response model for add\_member

### `class xdk.lists.models.CreateResponse`

Response model for create

### `class xdk.lists.models.DeleteResponse`

Response model for delete

### `class xdk.lists.models.GetByIdResponse`

Response model for get\_by\_id

### `class xdk.lists.models.GetFollowersResponse`

Response model for get\_followers

### `class xdk.lists.models.GetMembersResponse`

Response model for get\_members

### `class xdk.lists.models.GetPostsResponse`

Response model for get\_posts

### `class xdk.lists.models.RemoveMemberByUserIdResponse`

Response model for remove\_member\_by\_user\_id

### `class xdk.lists.models.UpdateResponse`

Response model for update


# MediaClient
Source: https://docs.x.com/xdks/python/reference/xdk.media

Reference for the media Python package in the X API SDK, grouping the client and Pydantic models for the media endpoints of the X API v2.

## Submodules

* [xdk.media.client module](/xdks/python/reference/xdk.media.client)
  * [`MediaClient`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient)
    * [`MediaClient.__init__()`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient.__init__)
    * [`MediaClient.append_upload()`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient.append_upload)
    * [`MediaClient.create_metadata()`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient.create_metadata)
    * [`MediaClient.create_subtitles()`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient.create_subtitles)
    * [`MediaClient.delete_subtitles()`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient.delete_subtitles)
    * [`MediaClient.finalize_upload()`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient.finalize_upload)
    * [`MediaClient.get_analytics()`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient.get_analytics)
    * [`MediaClient.get_by_key()`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient.get_by_key)
    * [`MediaClient.get_by_keys()`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient.get_by_keys)
    * [`MediaClient.get_upload_status()`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient.get_upload_status)
    * [`MediaClient.initialize_upload()`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient.initialize_upload)
    * [`MediaClient.upload()`](/xdks/python/reference/xdk.media.client#xdk.media.client.MediaClient.upload)
* [xdk.media.models module](/xdks/python/reference/xdk.media.models)
  * [`AppendUploadRequest`](/xdks/python/reference/xdk.media.models#xdk.media.models.AppendUploadRequest)
    * [`AppendUploadRequest.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.AppendUploadRequest.model_config)
  * [`AppendUploadResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.AppendUploadResponse)
    * [`AppendUploadResponse.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.AppendUploadResponse.model_config)
  * [`CreateMetadataRequest`](/xdks/python/reference/xdk.media.models#xdk.media.models.CreateMetadataRequest)
    * [`CreateMetadataRequest.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.CreateMetadataRequest.model_config)
  * [`CreateMetadataResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.CreateMetadataResponse)
    * [`CreateMetadataResponse.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.CreateMetadataResponse.model_config)
  * [`CreateSubtitlesRequest`](/xdks/python/reference/xdk.media.models#xdk.media.models.CreateSubtitlesRequest)
    * [`CreateSubtitlesRequest.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.CreateSubtitlesRequest.model_config)
  * [`CreateSubtitlesResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.CreateSubtitlesResponse)
    * [`CreateSubtitlesResponse.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.CreateSubtitlesResponse.model_config)
  * [`DeleteSubtitlesRequest`](/xdks/python/reference/xdk.media.models#xdk.media.models.DeleteSubtitlesRequest)
    * [`DeleteSubtitlesRequest.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.DeleteSubtitlesRequest.model_config)
  * [`DeleteSubtitlesResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.DeleteSubtitlesResponse)
    * [`DeleteSubtitlesResponse.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.DeleteSubtitlesResponse.model_config)
  * [`FinalizeUploadResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.FinalizeUploadResponse)
    * [`FinalizeUploadResponse.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.FinalizeUploadResponse.model_config)
  * [`GetAnalyticsResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.GetAnalyticsResponse)
    * [`GetAnalyticsResponse.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.GetAnalyticsResponse.model_config)
  * [`GetByKeyResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.GetByKeyResponse)
    * [`GetByKeyResponse.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.GetByKeyResponse.model_config)
  * [`GetByKeysResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.GetByKeysResponse)
    * [`GetByKeysResponse.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.GetByKeysResponse.model_config)
  * [`GetUploadStatusResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.GetUploadStatusResponse)
    * [`GetUploadStatusResponse.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.GetUploadStatusResponse.model_config)
  * [`InitializeUploadRequest`](/xdks/python/reference/xdk.media.models#xdk.media.models.InitializeUploadRequest)
    * [`InitializeUploadRequest.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.InitializeUploadRequest.model_config)
  * [`InitializeUploadResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.InitializeUploadResponse)
    * [`InitializeUploadResponse.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.InitializeUploadResponse.model_config)
  * [`UploadRequest`](/xdks/python/reference/xdk.media.models#xdk.media.models.UploadRequest)
    * [`UploadRequest.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.UploadRequest.model_config)
  * [`UploadResponse`](/xdks/python/reference/xdk.media.models#xdk.media.models.UploadResponse)
    * [`UploadResponse.model_config`](/xdks/python/reference/xdk.media.models#xdk.media.models.UploadResponse.model_config)

## Module contents

This module provides access to the media endpoints of the X API
and serves as the main entry point for all media-related functionality.

### `class xdk.media.MediaClient`

Client for media operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `append_upload`

Append Media upload
Appends data to a Media upload request.

#### Parameters

<ParamField type="Any">
  The media identifier for the media to perform the append operation.
</ParamField>

<ParamField type="AppendUploadRequest">
  Request body
</ParamField>

### `create_metadata`

Create Media metadata
Creates metadata for a Media file.
body: Request body
:returns: Response data
:rtype: CreateMetadataResponse

#### Parameters

<ParamField type="CreateMetadataRequest" />

### `create_subtitles`

Create Media subtitles
Creates subtitles for a specific Media file.
body: Request body
:returns: Response data
:rtype: CreateSubtitlesResponse

#### Parameters

<ParamField type="CreateSubtitlesRequest" />

### `delete_subtitles`

Delete Media subtitles
Deletes subtitles for a specific Media file.
body: Request body
:returns: Response data
:rtype: DeleteSubtitlesResponse

#### Parameters

<ParamField type="DeleteSubtitlesRequest" />

### `finalize_upload`

Finalize Media upload
Finalizes a Media upload request.

#### Parameters

<ParamField type="Any">
  The media id of the targeted media to finalize.
</ParamField>

#### Returns

`FinalizeUploadResponse` - Response data

### `get_analytics`

Get Media analytics
Retrieves analytics data for media.

#### Parameters

<ParamField type="List">
  A comma separated list of Media Keys. Up to 100 are allowed in a single request.
</ParamField>

<ParamField type="str">
  YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the end of the time range.
</ParamField>

<ParamField type="str">
  YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the start of the time range.
</ParamField>

<ParamField type="str">
  The granularity for the search counts results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of MediaAnalytics fields to display.
</ParamField>

#### Returns

`GetAnalyticsResponse` - Response data

### `get_by_key`

Get Media by media key
Retrieves details of a specific Media file by its media key.

#### Parameters

<ParamField type="Any">
  A single Media Key.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

#### Returns

`GetByKeyResponse` - Response data

### `get_by_keys`

Get Media by media keys
Retrieves details of Media files by their media keys.

#### Parameters

<ParamField type="List">
  A comma separated list of Media Keys. Up to 100 are allowed in a single request.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

#### Returns

`GetByKeysResponse` - Response data

### `get_upload_status`

Get Media upload status
Retrieves the status of a Media upload by its ID.

#### Parameters

<ParamField type="Any">
  Media id for the requested media upload status.
</ParamField>

<ParamField type="str or None">
  The command for the media upload request.
</ParamField>

#### Returns

`GetUploadStatusResponse` - Response data

### `initialize_upload`

Initialize media upload
Initializes a media upload.
body: Request body
:returns: Response data
:rtype: InitializeUploadResponse

#### Parameters

<ParamField type="InitializeUploadRequest" />

### `upload`

Upload media
Uploads a media file for use in posts or other content.
body: Request body
:returns: Response data
:rtype: UploadResponse

#### Parameters

<ParamField type="UploadRequest" />


# MediaClient
Source: https://docs.x.com/xdks/python/reference/xdk.media.client

Reference for the media.client Python module in the X API SDK. Client class and methods for calling the media endpoints of the X API v2.

## MediaClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for media operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `append_upload`

Append Media upload
Appends data to a Media upload request.

#### Parameters

<ParamField type="Any">
  The media identifier for the media to perform the append operation.
</ParamField>

<ParamField type="AppendUploadRequest">
  Request body
</ParamField>

### `create_metadata`

Create Media metadata
Creates metadata for a Media file.
body: Request body
:returns: Response data
:rtype: CreateMetadataResponse

#### Parameters

<ParamField type="CreateMetadataRequest" />

### `create_subtitles`

Create Media subtitles
Creates subtitles for a specific Media file.
body: Request body
:returns: Response data
:rtype: CreateSubtitlesResponse

#### Parameters

<ParamField type="CreateSubtitlesRequest" />

### `delete_subtitles`

Delete Media subtitles
Deletes subtitles for a specific Media file.
body: Request body
:returns: Response data
:rtype: DeleteSubtitlesResponse

#### Parameters

<ParamField type="DeleteSubtitlesRequest" />

### `finalize_upload`

Finalize Media upload
Finalizes a Media upload request.

#### Parameters

<ParamField type="Any">
  The media id of the targeted media to finalize.
</ParamField>

#### Returns

`FinalizeUploadResponse` - Response data

### `get_analytics`

Get Media analytics
Retrieves analytics data for media.

#### Parameters

<ParamField type="List">
  A comma separated list of Media Keys. Up to 100 are allowed in a single request.
</ParamField>

<ParamField type="str">
  YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the end of the time range.
</ParamField>

<ParamField type="str">
  YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the start of the time range.
</ParamField>

<ParamField type="str">
  The granularity for the search counts results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of MediaAnalytics fields to display.
</ParamField>

#### Returns

`GetAnalyticsResponse` - Response data

### `get_by_key`

Get Media by media key
Retrieves details of a specific Media file by its media key.

#### Parameters

<ParamField type="Any">
  A single Media Key.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

#### Returns

`GetByKeyResponse` - Response data

### `get_by_keys`

Get Media by media keys
Retrieves details of Media files by their media keys.

#### Parameters

<ParamField type="List">
  A comma separated list of Media Keys. Up to 100 are allowed in a single request.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

#### Returns

`GetByKeysResponse` - Response data

### `get_upload_status`

Get Media upload status
Retrieves the status of a Media upload by its ID.

#### Parameters

<ParamField type="Any">
  Media id for the requested media upload status.
</ParamField>

<ParamField type="str or None">
  The command for the media upload request.
</ParamField>

#### Returns

`GetUploadStatusResponse` - Response data

### `initialize_upload`

Initialize media upload
Initializes a media upload.
body: Request body
:returns: Response data
:rtype: InitializeUploadResponse

#### Parameters

<ParamField type="InitializeUploadRequest" />

### `upload`

Upload media
Uploads a media file for use in posts or other content.
body: Request body
:returns: Response data
:rtype: UploadResponse

#### Parameters

<ParamField type="UploadRequest" />


# Media.Models
Source: https://docs.x.com/xdks/python/reference/xdk.media.models

Reference for the media.models Python module in the X API SDK. Pydantic request and response models for the media endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the media endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

### class xdk.media.models.AppendUploadRequest

Request model for append\_upload

<ResponseField name="model_config" type="ConfigDict">
  Default: `{'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}`

  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
</ResponseField>

## AppendUploadResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for append\_upload

## Methods

### `class xdk.media.models.AppendUploadResponse`

Response model for append\_upload

### `class xdk.media.models.CreateMetadataResponse`

Response model for create\_metadata

### `class xdk.media.models.CreateSubtitlesResponse`

Response model for create\_subtitles

### `class xdk.media.models.DeleteSubtitlesResponse`

Response model for delete\_subtitles

### `class xdk.media.models.FinalizeUploadResponse`

Response model for finalize\_upload

### `class xdk.media.models.GetAnalyticsResponse`

Response model for get\_analytics

### `class xdk.media.models.GetByKeyResponse`

Response model for get\_by\_key

### `class xdk.media.models.GetByKeysResponse`

Response model for get\_by\_keys

### `class xdk.media.models.GetUploadStatusResponse`

Response model for get\_upload\_status

### `class xdk.media.models.InitializeUploadResponse`

Response model for initialize\_upload

### `class xdk.media.models.UploadResponse`

Response model for upload


# NewsClient
Source: https://docs.x.com/xdks/python/reference/xdk.news

Reference for the news Python package in the X API SDK, grouping the client and Pydantic models for the news endpoints of the X API v2.

## Submodules

* [xdk.news.client module](/xdks/python/reference/xdk.news.client)
  * [`NewsClient`](/xdks/python/reference/xdk.news.client#xdk.news.client.NewsClient)
    * [`NewsClient.__init__()`](/xdks/python/reference/xdk.news.client#xdk.news.client.NewsClient.__init__)
    * [`NewsClient.get()`](/xdks/python/reference/xdk.news.client#xdk.news.client.NewsClient.get)
    * [`NewsClient.search()`](/xdks/python/reference/xdk.news.client#xdk.news.client.NewsClient.search)
* [xdk.news.models module](/xdks/python/reference/xdk.news.models)
  * [`GetResponse`](/xdks/python/reference/xdk.news.models#xdk.news.models.GetResponse)
    * [`GetResponse.model_config`](/xdks/python/reference/xdk.news.models#xdk.news.models.GetResponse.model_config)
  * [`SearchResponse`](/xdks/python/reference/xdk.news.models#xdk.news.models.SearchResponse)
    * [`SearchResponse.model_config`](/xdks/python/reference/xdk.news.models#xdk.news.models.SearchResponse.model_config)

## Module contents

This module provides access to the news endpoints of the X API
and serves as the main entry point for all news-related functionality.

### `class xdk.news.NewsClient`

Client for news operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get`

Get news stories by ID
Retrieves news story by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the news story.
</ParamField>

<ParamField type="List or None">
  A comma separated list of News fields to display.
</ParamField>

#### Returns

`GetResponse` - Response data

### `search`

Search News
Retrieves a list of News stories matching the specified search query.

#### Parameters

<ParamField type="str">
  The search query.
</ParamField>

<ParamField type="int or None">
  The number of results to return.
</ParamField>

<ParamField type="int or None">
  The maximum age of the News story to search for.
</ParamField>

<ParamField type="List or None">
  A comma separated list of News fields to display.
</ParamField>

#### Returns

`SearchResponse` - Response data


# NewsClient
Source: https://docs.x.com/xdks/python/reference/xdk.news.client

Reference for the news.client Python module in the X API SDK. Client class and methods for calling the news endpoints of the X API v2.

## NewsClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for news operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get`

Get news stories by ID
Retrieves news story by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the news story.
</ParamField>

<ParamField type="List or None">
  A comma separated list of News fields to display.
</ParamField>

#### Returns

`GetResponse` - Response data

### `search`

Search News
Retrieves a list of News stories matching the specified search query.

#### Parameters

<ParamField type="str">
  The search query.
</ParamField>

<ParamField type="int or None">
  The number of results to return.
</ParamField>

<ParamField type="int or None">
  The maximum age of the News story to search for.
</ParamField>

<ParamField type="List or None">
  A comma separated list of News fields to display.
</ParamField>

#### Returns

`SearchResponse` - Response data


# News.Models
Source: https://docs.x.com/xdks/python/reference/xdk.news.models

Reference for the news.models Python module in the X API SDK. Pydantic request and response models for the news endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the news endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

## GetResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for get

## Methods

### `class xdk.news.models.GetResponse`

Response model for get

### `class xdk.news.models.SearchResponse`

Response model for search


# oauth1_auth
Source: https://docs.x.com/xdks/python/reference/xdk.oauth1_auth

Reference for the oauth1_auth Python package in the X API SDK, grouping the client and Pydantic models for the oauth1 auth endpoints of the X API v2.

This module provides OAuth1.0a authentication functionality for secure
authorization flows. Includes request token generation, authorization URL
generation, access token exchange, and OAuth1 signature generation.

### `class xdk.oauth1_auth.OAuth1`

OAuth1 authentication handler for the X API.

#### Parameters

<ParamField type="str" />

<ParamField type="str" />

<ParamField type="str" />

<ParamField type="str or None" />

<ParamField type="str or None" />

### `__init__`

Initialize OAuth1 authentication.

#### Parameters

<ParamField type="str">
  API Key (Consumer Key).
</ParamField>

<ParamField type="str">
  API Secret (Consumer Secret).
</ParamField>

<ParamField type="str">
  Callback URL for OAuth flow.
</ParamField>

<ParamField type="str or None">
  Access Token (if already obtained).
</ParamField>

<ParamField type="str or None">
  Access Token Secret (if already obtained).
</ParamField>

### `build_request_header`

Build OAuth1 authorization header for API requests.

#### Parameters

<ParamField type="str">
  HTTP method (GET, POST, etc.).
</ParamField>

<ParamField type="str">
  Request URL (may include query parameters).
</ParamField>

<ParamField type="str">
  Request body (form-encoded string or empty).
</ParamField>

#### Returns

`str`

### `get_access_token`

Exchange verifier for access token.

#### Parameters

<ParamField type="str">
  OAuth verifier from callback or PIN.
</ParamField>

#### Returns

`OAuth1AccessToken`

### `get_authorization_url`

Get the authorization URL for OAuth1 flow.

#### Parameters

<ParamField type="bool">
  Whether to use “Log in with X” flow.
</ParamField>

#### Returns

`str`

### `get_request_token`

Get request token to start OAuth1 flow.
:returns: Request token with oauth\_token and oauth\_token\_secret.
:rtype: OAuth1RequestToken

#### Returns

`OAuth1RequestToken`

### `start_oauth_flow`

Convenience method to start the OAuth1 flow.

#### Parameters

<ParamField type="bool">
  Whether to use “Log in with X” flow.
</ParamField>

#### Returns

`str`

### `class xdk.oauth1_auth.OAuth1AccessToken`

OAuth1 access token response.

#### Parameters

<ParamField type="str" />

<ParamField type="str" />

### `__init__`

Initialize OAuth1 access token.

#### Parameters

<ParamField type="str">
  The access token.
</ParamField>

<ParamField type="str">
  The access token secret.
</ParamField>

### `class xdk.oauth1_auth.OAuth1RequestToken`

OAuth1 request token response.

#### Parameters

<ParamField type="str" />

<ParamField type="str" />

### `__init__`

Initialize OAuth1 request token.

#### Parameters

<ParamField type="str">
  The OAuth token.
</ParamField>

<ParamField type="str">
  The OAuth token secret.
</ParamField>


# OAuth2PKCEAuth
Source: https://docs.x.com/xdks/python/reference/xdk.oauth2_auth

Reference for the oauth2_auth Python package in the X API SDK, grouping the client and Pydantic models for the oauth2 auth endpoints of the X API v2.

This module provides OAuth2 PKCE (Proof Key for Code Exchange) authentication
functionality for secure authorization flows. Includes code verifier generation,
token management, and automatic token refresh capabilities.

### `class xdk.oauth2_auth.OAuth2PKCEAuth`

OAuth2 PKCE authentication for the X API.

#### Parameters

<ParamField type="str" />

<ParamField type="str" />

<ParamField type="str or None" />

<ParamField type="str or None" />

<ParamField type="str or None" />

<ParamField type="Dict[str, Any] or None" />

<ParamField type="str or List[str] or None" />

### `__init__`

Initialize the OAuth2 PKCE authentication.

#### Parameters

<ParamField type="str">
  The base URL for the X API token endpoint (defaults to [https://api.x.com](https://api.x.com)).
</ParamField>

<ParamField type="str">
  The base URL for OAuth2 authorization (defaults to [https://x.com/i](https://x.com/i)).
</ParamField>

<ParamField type="str or None">
  The client ID for the X API.
</ParamField>

<ParamField type="str or None">
  The client secret for the X API.
</ParamField>

<ParamField type="str or None">
  The redirect URI for OAuth2 authorization.
</ParamField>

<ParamField type="Dict[str, Any] or None">
  An existing OAuth2 token dictionary (if available).
</ParamField>

<ParamField type="str or List[str] or None">
  Space-separated string or list of strings for OAuth2 authorization scopes.
</ParamField>

### `exchange_code`

Exchange authorization code for tokens (matches TypeScript API).

#### Parameters

<ParamField type="str">
  The authorization code from the callback.
</ParamField>

<ParamField type="str or None">
  Optional code verifier (uses stored verifier if not provided).
</ParamField>

#### Returns

`Dictstr, Any`

### `fetch_token`

Fetch token using authorization response URL (legacy method, uses exchange\_code internally).

#### Parameters

<ParamField type="str">
  The full callback URL received after authorization
</ParamField>

#### Returns

`Dictstr, Any`

### `get_authorization_url`

Get the authorization URL for the OAuth2 PKCE flow.

#### Parameters

<ParamField type="str or None">
  Optional state parameter for security.
</ParamField>

#### Returns

`str`

### `get_code_challenge`

Get the current code challenge (for PKCE).
:returns: The current code challenge, or None if not set.
:rtype: Optional\[str]

#### Returns

`str | None`

### `get_code_verifier`

Get the current code verifier (for PKCE).
:returns: The current code verifier, or None if not set.
:rtype: Optional\[str]

#### Returns

`str | None`

### `is_token_expired`

Check if the token is expired.
:returns: True if the token is expired, False otherwise.
:rtype: bool

#### Returns

`bool`

### `refresh_token`

Refresh the access token.
:returns: The refreshed token dictionary
:rtype: Dict\[str, Any]

#### Returns

`Dictstr, Any`

### `set_pkce_parameters`

Manually set PKCE parameters.

#### Parameters

<ParamField type="str">
  The code verifier to use.
</ParamField>

<ParamField type="str or None">
  Optional code challenge (will be generated if not provided).
</ParamField>


# paginator
Source: https://docs.x.com/xdks/python/reference/xdk.paginator

Reference for the paginator Python package in the X API SDK, grouping the client and Pydantic models for the paginator endpoints of the X API v2.

Cursor-based pagination utilities for the X API SDK.

This module provides a Cursor class for elegant pagination support across
all API clients. The Cursor enables easy iteration over paginated results
using both .pages() and .items() methods with proper type safety.

### `class xdk.paginator.Cursor`

\[`ResponseType`]

#### Parameters

<ParamField type="PaginatableMethod" />

### `__init__`

Initialize the cursor.

#### Parameters

<ParamField type="PaginatableMethod">
  The API method to call for each page (must support pagination)
</ParamField>

### `items`

Iterate over individual items from paginated responses.

#### Parameters

<ParamField type="int or None">
  Maximum number of items to return (None for unlimited)
</ParamField>

#### Returns

`IteratorAny`

### `pages`

Iterate over pages of responses.

#### Parameters

<ParamField type="int or None">
  Maximum number of pages to return (None for unlimited)
</ParamField>

#### Returns

`IteratorResponseType`

### `class xdk.paginator.PaginatableMethod`

\[`ResponseType`]

### `__init__`

### `xdk.paginator.cursor`

Create a cursor with proper type inference and validation.
This factory function helps with type inference so you get proper
type hints for the response type, and validates that the method
supports pagination at both static analysis and runtime.

#### Parameters

<ParamField type="PaginatableMethod">
  The API method to wrap (must support pagination)
</ParamField>


# PostsClient
Source: https://docs.x.com/xdks/python/reference/xdk.posts

Reference for the posts Python package in the X API SDK, grouping the client and Pydantic models for the posts endpoints of the X API v2.

## Submodules

* [xdk.posts.client module](/xdks/python/reference/xdk.posts.client)
  * [`PostsClient`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient)
    * [`PostsClient.__init__()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.__init__)
    * [`PostsClient.create()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.create)
    * [`PostsClient.delete()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.delete)
    * [`PostsClient.get_analytics()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.get_analytics)
    * [`PostsClient.get_by_id()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.get_by_id)
    * [`PostsClient.get_by_ids()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.get_by_ids)
    * [`PostsClient.get_counts_all()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.get_counts_all)
    * [`PostsClient.get_counts_recent()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.get_counts_recent)
    * [`PostsClient.get_insights28hr()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.get_insights28hr)
    * [`PostsClient.get_insights_historical()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.get_insights_historical)
    * [`PostsClient.get_liking_users()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.get_liking_users)
    * [`PostsClient.get_quoted()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.get_quoted)
    * [`PostsClient.get_reposted_by()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.get_reposted_by)
    * [`PostsClient.get_reposts()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.get_reposts)
    * [`PostsClient.hide_reply()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.hide_reply)
    * [`PostsClient.search_all()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.search_all)
    * [`PostsClient.search_recent()`](/xdks/python/reference/xdk.posts.client#xdk.posts.client.PostsClient.search_recent)
* [xdk.posts.models module](/xdks/python/reference/xdk.posts.models)
  * [`CreateRequest`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.CreateRequest)
    * [`CreateRequest.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.CreateRequest.model_config)
  * [`CreateResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.CreateResponse)
    * [`CreateResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.CreateResponse.model_config)
  * [`DeleteResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.DeleteResponse)
    * [`DeleteResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.DeleteResponse.model_config)
  * [`GetAnalyticsResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetAnalyticsResponse)
    * [`GetAnalyticsResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetAnalyticsResponse.model_config)
  * [`GetByIdResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetByIdResponse)
    * [`GetByIdResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetByIdResponse.model_config)
  * [`GetByIdsResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetByIdsResponse)
    * [`GetByIdsResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetByIdsResponse.model_config)
  * [`GetCountsAllResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetCountsAllResponse)
    * [`GetCountsAllResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetCountsAllResponse.model_config)
  * [`GetCountsRecentResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetCountsRecentResponse)
    * [`GetCountsRecentResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetCountsRecentResponse.model_config)
  * [`GetInsights28hrResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetInsights28hrResponse)
    * [`GetInsights28hrResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetInsights28hrResponse.model_config)
  * [`GetInsightsHistoricalResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetInsightsHistoricalResponse)
    * [`GetInsightsHistoricalResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetInsightsHistoricalResponse.model_config)
  * [`GetLikingUsersResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetLikingUsersResponse)
    * [`GetLikingUsersResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetLikingUsersResponse.model_config)
  * [`GetQuotedResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetQuotedResponse)
    * [`GetQuotedResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetQuotedResponse.model_config)
  * [`GetRepostedByResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetRepostedByResponse)
    * [`GetRepostedByResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetRepostedByResponse.model_config)
  * [`GetRepostsResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetRepostsResponse)
    * [`GetRepostsResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.GetRepostsResponse.model_config)
  * [`HideReplyRequest`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.HideReplyRequest)
    * [`HideReplyRequest.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.HideReplyRequest.model_config)
  * [`HideReplyResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.HideReplyResponse)
    * [`HideReplyResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.HideReplyResponse.model_config)
  * [`SearchAllResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.SearchAllResponse)
    * [`SearchAllResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.SearchAllResponse.model_config)
  * [`SearchRecentResponse`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.SearchRecentResponse)
    * [`SearchRecentResponse.model_config`](/xdks/python/reference/xdk.posts.models#xdk.posts.models.SearchRecentResponse.model_config)

## Module contents

This module provides access to the posts endpoints of the X API
and serves as the main entry point for all posts-related functionality.

### `class xdk.posts.PostsClient`

Client for posts operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create`

Create or Edit Post
Creates a new Post for the authenticated user, or edits an existing Post when edit\_options are provided.
body: Request body
:returns: Response data
:rtype: CreateResponse

#### Parameters

<ParamField type="CreateRequest" />

### `delete`

Delete Post
Deletes a specific Post by its ID, if owned by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the Post to be deleted.
</ParamField>

#### Returns

`DeleteResponse` - Response data

### `get_analytics`

Get Post analytics
Retrieves analytics data for specified Posts within a defined time range.

#### Parameters

<ParamField type="List">
  A comma separated list of Post IDs. Up to 100 are allowed in a single request.
</ParamField>

<ParamField type="str">
  YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the end of the time range.
</ParamField>

<ParamField type="str">
  YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the start of the time range.
</ParamField>

<ParamField type="str">
  The granularity for the search counts results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Analytics fields to display.
</ParamField>

#### Returns

`GetAnalyticsResponse` - Response data

### `get_by_id`

Get Post by ID
Retrieves details of a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  A single Post ID.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`GetByIdResponse` - Response data

### `get_by_ids`

Get Posts by IDs
Retrieves details of multiple Posts by their IDs.

#### Parameters

<ParamField type="List">
  A comma separated list of Post IDs. Up to 100 are allowed in a single request.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`GetByIdsResponse` - Response data

### `get_counts_all`

Get count of all Posts
Retrieves the count of Posts matching a search query from the full archive.

#### Parameters

<ParamField type="str">
  One query/rule/filter for matching Posts. Refer to [https://t.co/rulelength](https://t.co/rulelength) to identify the max query length.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp (from most recent 7 days) from which the Posts will be provided. Timestamp is in second granularity and is inclusive (i.e. 12:00:01 includes the first second of the minute).
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp is in second granularity and is exclusive (i.e. 12:00:01 excludes the first second of the minute).
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID greater than (that is, more recent than) the specified ID.
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID less than (that is, older than) the specified ID.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="str or None">
  The granularity for the search counts results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of SearchCount fields to display.
</ParamField>

#### Returns

`IteratorGetCountsAllResponse`

### `get_counts_recent`

Get count of recent Posts
Retrieves the count of Posts from the last 7 days matching a search query.

#### Parameters

<ParamField type="str">
  One query/rule/filter for matching Posts. Refer to [https://t.co/rulelength](https://t.co/rulelength) to identify the max query length.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp (from most recent 7 days) from which the Posts will be provided. Timestamp is in second granularity and is inclusive (i.e. 12:00:01 includes the first second of the minute).
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp is in second granularity and is exclusive (i.e. 12:00:01 excludes the first second of the minute).
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID greater than (that is, more recent than) the specified ID.
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID less than (that is, older than) the specified ID.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="str or None">
  The granularity for the search counts results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of SearchCount fields to display.
</ParamField>

#### Returns

`IteratorGetCountsRecentResponse`

### `get_insights28hr`

Get 28-hour Post insights
Retrieves engagement metrics for specified Posts over the last 28 hours.

#### Parameters

<ParamField type="List">
  List of PostIds for 28hr metrics.
</ParamField>

<ParamField type="str">
  granularity of metrics response.
</ParamField>

<ParamField type="List">
  request metrics for historical request.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Engagement fields to display.
</ParamField>

#### Returns

`GetInsights28hrResponse` - Response data

### `get_insights_historical`

Get historical Post insights
Retrieves historical engagement metrics for specified Posts within a defined time range.

#### Parameters

<ParamField type="List">
  List of PostIds for historical metrics.
</ParamField>

<ParamField type="str">
  YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the end of the time range.
</ParamField>

<ParamField type="str">
  YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the start of the time range.
</ParamField>

<ParamField type="str">
  granularity of metrics response.
</ParamField>

<ParamField type="List">
  request metrics for historical request.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Engagement fields to display.
</ParamField>

#### Returns

`GetInsightsHistoricalResponse` - Response data

### `get_liking_users`

Get Liking Users
Retrieves a list of Users who liked a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  A single Post ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetLikingUsersResponse`

### `get_quoted`

Get Quoted Posts
Retrieves a list of Posts that quote a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  A single Post ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of results to be returned.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  The set of entities to exclude (e.g. ‘replies’ or ‘retweets’).
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetQuotedResponse`

### `get_reposted_by`

Get Reposted by
Retrieves a list of Users who reposted a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  A single Post ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetRepostedByResponse`

### `get_reposts`

Get Reposts
Retrieves a list of Posts that repost a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  A single Post ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetRepostsResponse`

### `hide_reply`

Hide reply
Hides or unhides a reply to a conversation owned by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the reply that you want to hide or unhide.
</ParamField>

<ParamField type="HideReplyRequest">
  Request body
</ParamField>

### `search_all`

Search all Posts
Retrieves Posts from the full archive matching a search query.

#### Parameters

<ParamField type="str">
  One query/rule/filter for matching Posts. Refer to [https://t.co/rulelength](https://t.co/rulelength) to identify the max query length.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp from which the Posts will be provided. Timestamp is in second granularity and is inclusive (i.e. 12:00:01 includes the first second of the minute).
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp is in second granularity and is exclusive (i.e. 12:00:01 excludes the first second of the minute).
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID greater than (that is, more recent than) the specified ID.
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID less than (that is, older than) the specified ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of search results to be returned by a request.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="str or None">
  This order in which to return results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorSearchAllResponse`

### `search_recent`

Search recent Posts
Retrieves Posts from the last 7 days matching a search query.

#### Parameters

<ParamField type="str">
  One query/rule/filter for matching Posts. Refer to [https://t.co/rulelength](https://t.co/rulelength) to identify the max query length.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp from which the Posts will be provided. Timestamp is in second granularity and is inclusive (i.e. 12:00:01 includes the first second of the minute).
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp is in second granularity and is exclusive (i.e. 12:00:01 excludes the first second of the minute).
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID greater than (that is, more recent than) the specified ID.
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID less than (that is, older than) the specified ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of search results to be returned by a request.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="str or None">
  This order in which to return results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorSearchRecentResponse`


# PostsClient
Source: https://docs.x.com/xdks/python/reference/xdk.posts.client

Reference for the posts.client Python module in the X API SDK. Client class and methods for calling the posts endpoints of the X API v2.

## PostsClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for posts operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create`

Create or Edit Post
Creates a new Post for the authenticated user, or edits an existing Post when edit\_options are provided.
body: Request body
:returns: Response data
:rtype: CreateResponse

#### Parameters

<ParamField type="CreateRequest" />

### `delete`

Delete Post
Deletes a specific Post by its ID, if owned by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the Post to be deleted.
</ParamField>

#### Returns

`DeleteResponse` - Response data

### `get_analytics`

Get Post analytics
Retrieves analytics data for specified Posts within a defined time range.

#### Parameters

<ParamField type="List">
  A comma separated list of Post IDs. Up to 100 are allowed in a single request.
</ParamField>

<ParamField type="str">
  YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the end of the time range.
</ParamField>

<ParamField type="str">
  YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the start of the time range.
</ParamField>

<ParamField type="str">
  The granularity for the search counts results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Analytics fields to display.
</ParamField>

#### Returns

`GetAnalyticsResponse` - Response data

### `get_by_id`

Get Post by ID
Retrieves details of a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  A single Post ID.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`GetByIdResponse` - Response data

### `get_by_ids`

Get Posts by IDs
Retrieves details of multiple Posts by their IDs.

#### Parameters

<ParamField type="List">
  A comma separated list of Post IDs. Up to 100 are allowed in a single request.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`GetByIdsResponse` - Response data

### `get_counts_all`

Get count of all Posts
Retrieves the count of Posts matching a search query from the full archive.

#### Parameters

<ParamField type="str">
  One query/rule/filter for matching Posts. Refer to [https://t.co/rulelength](https://t.co/rulelength) to identify the max query length.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp (from most recent 7 days) from which the Posts will be provided. Timestamp is in second granularity and is inclusive (i.e. 12:00:01 includes the first second of the minute).
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp is in second granularity and is exclusive (i.e. 12:00:01 excludes the first second of the minute).
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID greater than (that is, more recent than) the specified ID.
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID less than (that is, older than) the specified ID.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="str or None">
  The granularity for the search counts results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of SearchCount fields to display.
</ParamField>

#### Returns

`IteratorGetCountsAllResponse`

### `get_counts_recent`

Get count of recent Posts
Retrieves the count of Posts from the last 7 days matching a search query.

#### Parameters

<ParamField type="str">
  One query/rule/filter for matching Posts. Refer to [https://t.co/rulelength](https://t.co/rulelength) to identify the max query length.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp (from most recent 7 days) from which the Posts will be provided. Timestamp is in second granularity and is inclusive (i.e. 12:00:01 includes the first second of the minute).
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp is in second granularity and is exclusive (i.e. 12:00:01 excludes the first second of the minute).
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID greater than (that is, more recent than) the specified ID.
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID less than (that is, older than) the specified ID.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="str or None">
  The granularity for the search counts results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of SearchCount fields to display.
</ParamField>

#### Returns

`IteratorGetCountsRecentResponse`

### `get_insights28hr`

Get 28-hour Post insights
Retrieves engagement metrics for specified Posts over the last 28 hours.

#### Parameters

<ParamField type="List">
  List of PostIds for 28hr metrics.
</ParamField>

<ParamField type="str">
  granularity of metrics response.
</ParamField>

<ParamField type="List">
  request metrics for historical request.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Engagement fields to display.
</ParamField>

#### Returns

`GetInsights28hrResponse` - Response data

### `get_insights_historical`

Get historical Post insights
Retrieves historical engagement metrics for specified Posts within a defined time range.

#### Parameters

<ParamField type="List">
  List of PostIds for historical metrics.
</ParamField>

<ParamField type="str">
  YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the end of the time range.
</ParamField>

<ParamField type="str">
  YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the start of the time range.
</ParamField>

<ParamField type="str">
  granularity of metrics response.
</ParamField>

<ParamField type="List">
  request metrics for historical request.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Engagement fields to display.
</ParamField>

#### Returns

`GetInsightsHistoricalResponse` - Response data

### `get_liking_users`

Get Liking Users
Retrieves a list of Users who liked a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  A single Post ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetLikingUsersResponse`

### `get_quoted`

Get Quoted Posts
Retrieves a list of Posts that quote a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  A single Post ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of results to be returned.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  The set of entities to exclude (e.g. ‘replies’ or ‘retweets’).
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetQuotedResponse`

### `get_reposted_by`

Get Reposted by
Retrieves a list of Users who reposted a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  A single Post ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetRepostedByResponse`

### `get_reposts`

Get Reposts
Retrieves a list of Posts that repost a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  A single Post ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetRepostsResponse`

### `hide_reply`

Hide reply
Hides or unhides a reply to a conversation owned by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the reply that you want to hide or unhide.
</ParamField>

<ParamField type="HideReplyRequest">
  Request body
</ParamField>

### `search_all`

Search all Posts
Retrieves Posts from the full archive matching a search query.

#### Parameters

<ParamField type="str">
  One query/rule/filter for matching Posts. Refer to [https://t.co/rulelength](https://t.co/rulelength) to identify the max query length.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp from which the Posts will be provided. Timestamp is in second granularity and is inclusive (i.e. 12:00:01 includes the first second of the minute).
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp is in second granularity and is exclusive (i.e. 12:00:01 excludes the first second of the minute).
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID greater than (that is, more recent than) the specified ID.
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID less than (that is, older than) the specified ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of search results to be returned by a request.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="str or None">
  This order in which to return results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorSearchAllResponse`

### `search_recent`

Search recent Posts
Retrieves Posts from the last 7 days matching a search query.

#### Parameters

<ParamField type="str">
  One query/rule/filter for matching Posts. Refer to [https://t.co/rulelength](https://t.co/rulelength) to identify the max query length.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp from which the Posts will be provided. Timestamp is in second granularity and is inclusive (i.e. 12:00:01 includes the first second of the minute).
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp is in second granularity and is exclusive (i.e. 12:00:01 excludes the first second of the minute).
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID greater than (that is, more recent than) the specified ID.
</ParamField>

<ParamField type="Any or None">
  Returns results with a Post ID less than (that is, older than) the specified ID.
</ParamField>

<ParamField type="int or None">
  The maximum number of search results to be returned by a request.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="str or None">
  This order in which to return results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorSearchRecentResponse`


# Posts.Models
Source: https://docs.x.com/xdks/python/reference/xdk.posts.models

Reference for the posts.models Python module in the X API SDK. Pydantic request and response models for the posts endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the posts endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

### class xdk.posts.models.CreateRequest

Request model for create

<ResponseField name="model_config" type="ConfigDict">
  Default: `{'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}`

  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
</ResponseField>

## CreateResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for create

## Methods

### `class xdk.posts.models.CreateResponse`

Response model for create

### `class xdk.posts.models.DeleteResponse`

Response model for delete

### `class xdk.posts.models.GetAnalyticsResponse`

Response model for get\_analytics

### `class xdk.posts.models.GetByIdResponse`

Response model for get\_by\_id

### `class xdk.posts.models.GetByIdsResponse`

Response model for get\_by\_ids

### `class xdk.posts.models.GetCountsAllResponse`

Response model for get\_counts\_all

### `class xdk.posts.models.GetCountsRecentResponse`

Response model for get\_counts\_recent

### `class xdk.posts.models.GetInsights28hrResponse`

Response model for get\_insights28hr

### `class xdk.posts.models.GetInsightsHistoricalResponse`

Response model for get\_insights\_historical

### `class xdk.posts.models.GetLikingUsersResponse`

Response model for get\_liking\_users

### `class xdk.posts.models.GetQuotedResponse`

Response model for get\_quoted

### `class xdk.posts.models.GetRepostedByResponse`

Response model for get\_reposted\_by

### `class xdk.posts.models.GetRepostsResponse`

Response model for get\_reposts

### `class xdk.posts.models.HideReplyResponse`

Response model for hide\_reply

### `class xdk.posts.models.SearchAllResponse`

Response model for search\_all

### `class xdk.posts.models.SearchRecentResponse`

Response model for search\_recent


# SpacesClient
Source: https://docs.x.com/xdks/python/reference/xdk.spaces

Reference for the spaces Python package in the X API SDK, grouping the client and Pydantic models for the spaces endpoints of the X API v2.

## Submodules

* [xdk.spaces.client module](/xdks/python/reference/xdk.spaces.client)
  * [`SpacesClient`](/xdks/python/reference/xdk.spaces.client#xdk.spaces.client.SpacesClient)
    * [`SpacesClient.__init__()`](/xdks/python/reference/xdk.spaces.client#xdk.spaces.client.SpacesClient.__init__)
    * [`SpacesClient.get_buyers()`](/xdks/python/reference/xdk.spaces.client#xdk.spaces.client.SpacesClient.get_buyers)
    * [`SpacesClient.get_by_creator_ids()`](/xdks/python/reference/xdk.spaces.client#xdk.spaces.client.SpacesClient.get_by_creator_ids)
    * [`SpacesClient.get_by_id()`](/xdks/python/reference/xdk.spaces.client#xdk.spaces.client.SpacesClient.get_by_id)
    * [`SpacesClient.get_by_ids()`](/xdks/python/reference/xdk.spaces.client#xdk.spaces.client.SpacesClient.get_by_ids)
    * [`SpacesClient.get_posts()`](/xdks/python/reference/xdk.spaces.client#xdk.spaces.client.SpacesClient.get_posts)
    * [`SpacesClient.search()`](/xdks/python/reference/xdk.spaces.client#xdk.spaces.client.SpacesClient.search)
* [xdk.spaces.models module](/xdks/python/reference/xdk.spaces.models)
  * [`GetBuyersResponse`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetBuyersResponse)
    * [`GetBuyersResponse.model_config`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetBuyersResponse.model_config)
  * [`GetByCreatorIdsResponse`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetByCreatorIdsResponse)
    * [`GetByCreatorIdsResponse.model_config`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetByCreatorIdsResponse.model_config)
  * [`GetByIdResponse`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetByIdResponse)
    * [`GetByIdResponse.model_config`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetByIdResponse.model_config)
  * [`GetByIdsResponse`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetByIdsResponse)
    * [`GetByIdsResponse.model_config`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetByIdsResponse.model_config)
  * [`GetPostsResponse`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetPostsResponse)
    * [`GetPostsResponse.model_config`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.GetPostsResponse.model_config)
  * [`SearchResponse`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.SearchResponse)
    * [`SearchResponse.model_config`](/xdks/python/reference/xdk.spaces.models#xdk.spaces.models.SearchResponse.model_config)

## Module contents

This module provides access to the spaces endpoints of the X API
and serves as the main entry point for all spaces-related functionality.

### `class xdk.spaces.SpacesClient`

Client for spaces operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get_buyers`

Get Space ticket buyers
Retrieves a list of Users who purchased tickets to a specific Space by its ID.

#### Parameters

<ParamField type="str">
  The ID of the Space to be retrieved.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetBuyersResponse`

### `get_by_creator_ids`

Get Spaces by creator IDs
Retrieves details of Spaces created by specified User IDs.

#### Parameters

<ParamField type="List">
  The IDs of Users to search through.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Space fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Topic fields to display.
</ParamField>

#### Returns

`GetByCreatorIdsResponse` - Response data

### `get_by_id`

Get space by ID
Retrieves details of a specific space by its ID.

#### Parameters

<ParamField type="str">
  The ID of the Space to be retrieved.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Space fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Topic fields to display.
</ParamField>

#### Returns

`GetByIdResponse` - Response data

### `get_by_ids`

Get Spaces by IDs
Retrieves details of multiple Spaces by their IDs.

#### Parameters

<ParamField type="List">
  The list of Space IDs to return.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Space fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Topic fields to display.
</ParamField>

#### Returns

`GetByIdsResponse` - Response data

### `get_posts`

Get Space Posts
Retrieves a list of Posts shared in a specific Space by its ID.

#### Parameters

<ParamField type="str">
  The ID of the Space to be retrieved.
</ParamField>

<ParamField type="int or None">
  The number of Posts to fetch from the provided space. If not provided, the value will default to the maximum of 100.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`GetPostsResponse` - Response data

### `search`

Search Spaces
Retrieves a list of Spaces matching the specified search query.

#### Parameters

<ParamField type="str">
  The search query.
</ParamField>

<ParamField type="str or None">
  The state of Spaces to search for.
</ParamField>

<ParamField type="int or None">
  The number of results to return.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Space fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Topic fields to display.
</ParamField>

#### Returns

`SearchResponse` - Response data


# SpacesClient
Source: https://docs.x.com/xdks/python/reference/xdk.spaces.client

Reference for the spaces.client Python module in the X API SDK. Client class and methods for calling the spaces endpoints of the X API v2.

## SpacesClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for spaces operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get_buyers`

Get Space ticket buyers
Retrieves a list of Users who purchased tickets to a specific Space by its ID.

#### Parameters

<ParamField type="str">
  The ID of the Space to be retrieved.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetBuyersResponse`

### `get_by_creator_ids`

Get Spaces by creator IDs
Retrieves details of Spaces created by specified User IDs.

#### Parameters

<ParamField type="List">
  The IDs of Users to search through.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Space fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Topic fields to display.
</ParamField>

#### Returns

`GetByCreatorIdsResponse` - Response data

### `get_by_id`

Get space by ID
Retrieves details of a specific space by its ID.

#### Parameters

<ParamField type="str">
  The ID of the Space to be retrieved.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Space fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Topic fields to display.
</ParamField>

#### Returns

`GetByIdResponse` - Response data

### `get_by_ids`

Get Spaces by IDs
Retrieves details of multiple Spaces by their IDs.

#### Parameters

<ParamField type="List">
  The list of Space IDs to return.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Space fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Topic fields to display.
</ParamField>

#### Returns

`GetByIdsResponse` - Response data

### `get_posts`

Get Space Posts
Retrieves a list of Posts shared in a specific Space by its ID.

#### Parameters

<ParamField type="str">
  The ID of the Space to be retrieved.
</ParamField>

<ParamField type="int or None">
  The number of Posts to fetch from the provided space. If not provided, the value will default to the maximum of 100.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`GetPostsResponse` - Response data

### `search`

Search Spaces
Retrieves a list of Spaces matching the specified search query.

#### Parameters

<ParamField type="str">
  The search query.
</ParamField>

<ParamField type="str or None">
  The state of Spaces to search for.
</ParamField>

<ParamField type="int or None">
  The number of results to return.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Space fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Topic fields to display.
</ParamField>

#### Returns

`SearchResponse` - Response data


# Spaces.Models
Source: https://docs.x.com/xdks/python/reference/xdk.spaces.models

Reference for the spaces.models Python module in the X API SDK. Pydantic request and response models for the spaces endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the spaces endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

## GetBuyersResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for get\_buyers

## Methods

### `class xdk.spaces.models.GetBuyersResponse`

Response model for get\_buyers

### `class xdk.spaces.models.GetByCreatorIdsResponse`

Response model for get\_by\_creator\_ids

### `class xdk.spaces.models.GetByIdResponse`

Response model for get\_by\_id

### `class xdk.spaces.models.GetByIdsResponse`

Response model for get\_by\_ids

### `class xdk.spaces.models.GetPostsResponse`

Response model for get\_posts

### `class xdk.spaces.models.SearchResponse`

Response model for search


# StreamClient
Source: https://docs.x.com/xdks/python/reference/xdk.stream

Reference for the stream Python package in the X API SDK, grouping the client and Pydantic models for the stream endpoints of the X API v2.

## Submodules

* [xdk.stream.client module](/xdks/python/reference/xdk.stream.client)
  * [`StreamClient`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient)
    * [`StreamClient.__init__()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.__init__)
    * [`StreamClient.get_rule_counts()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.get_rule_counts)
    * [`StreamClient.get_rules()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.get_rules)
    * [`StreamClient.labels_compliance()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.labels_compliance)
    * [`StreamClient.likes_compliance()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.likes_compliance)
    * [`StreamClient.likes_firehose()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.likes_firehose)
    * [`StreamClient.likes_sample10()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.likes_sample10)
    * [`StreamClient.posts()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.posts)
    * [`StreamClient.posts_compliance()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.posts_compliance)
    * [`StreamClient.posts_firehose()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.posts_firehose)
    * [`StreamClient.posts_firehose_en()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.posts_firehose_en)
    * [`StreamClient.posts_firehose_ja()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.posts_firehose_ja)
    * [`StreamClient.posts_firehose_ko()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.posts_firehose_ko)
    * [`StreamClient.posts_firehose_pt()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.posts_firehose_pt)
    * [`StreamClient.posts_sample()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.posts_sample)
    * [`StreamClient.posts_sample10()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.posts_sample10)
    * [`StreamClient.update_rules()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.update_rules)
    * [`StreamClient.users_compliance()`](/xdks/python/reference/xdk.stream.client#xdk.stream.client.StreamClient.users_compliance)
* [xdk.stream.models module](/xdks/python/reference/xdk.stream.models)
  * [`GetRuleCountsResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.GetRuleCountsResponse)
    * [`GetRuleCountsResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.GetRuleCountsResponse.model_config)
  * [`GetRulesResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.GetRulesResponse)
    * [`GetRulesResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.GetRulesResponse.model_config)
  * [`LabelsComplianceResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.LabelsComplianceResponse)
    * [`LabelsComplianceResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.LabelsComplianceResponse.model_config)
  * [`LikesComplianceResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.LikesComplianceResponse)
    * [`LikesComplianceResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.LikesComplianceResponse.model_config)
  * [`LikesFirehoseResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.LikesFirehoseResponse)
    * [`LikesFirehoseResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.LikesFirehoseResponse.model_config)
  * [`LikesSample10Response`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.LikesSample10Response)
    * [`LikesSample10Response.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.LikesSample10Response.model_config)
  * [`PostsComplianceResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsComplianceResponse)
    * [`PostsComplianceResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsComplianceResponse.model_config)
  * [`PostsFirehoseEnResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehoseEnResponse)
    * [`PostsFirehoseEnResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehoseEnResponse.model_config)
  * [`PostsFirehoseJaResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehoseJaResponse)
    * [`PostsFirehoseJaResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehoseJaResponse.model_config)
  * [`PostsFirehoseKoResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehoseKoResponse)
    * [`PostsFirehoseKoResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehoseKoResponse.model_config)
  * [`PostsFirehosePtResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehosePtResponse)
    * [`PostsFirehosePtResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehosePtResponse.model_config)
  * [`PostsFirehoseResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehoseResponse)
    * [`PostsFirehoseResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsFirehoseResponse.model_config)
  * [`PostsResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsResponse)
    * [`PostsResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsResponse.model_config)
  * [`PostsSample10Response`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsSample10Response)
    * [`PostsSample10Response.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsSample10Response.model_config)
  * [`PostsSampleResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsSampleResponse)
    * [`PostsSampleResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.PostsSampleResponse.model_config)
  * [`UpdateRulesRequest`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.UpdateRulesRequest)
    * [`UpdateRulesRequest.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.UpdateRulesRequest.model_config)
  * [`UpdateRulesResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.UpdateRulesResponse)
    * [`UpdateRulesResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.UpdateRulesResponse.model_config)
  * [`UsersComplianceResponse`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.UsersComplianceResponse)
    * [`UsersComplianceResponse.model_config`](/xdks/python/reference/xdk.stream.models#xdk.stream.models.UsersComplianceResponse.model_config)

## Module contents

This module provides access to the stream endpoints of the X API
and serves as the main entry point for all stream-related functionality.

### `class xdk.stream.StreamClient`

Streaming Client for stream operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get_rule_counts`

Get stream rule counts
Retrieves the count of rules in the active rule set for the filtered stream.

#### Parameters

<ParamField type="List or None">
  A comma separated list of RulesCount fields to display.
</ParamField>

#### Returns

`GetRuleCountsResponse` - Response data

### `get_rules`

Get stream rules
Retrieves the active rule set or a subset of rules for the filtered stream.

#### Parameters

<ParamField type="List or None">
  A comma-separated list of Rule IDs.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="str or None">
  This value is populated by passing the ‘next\_token’ returned in a request to paginate through results.
</ParamField>

#### Returns

`IteratorGetRulesResponse`

### `labels_compliance`

Stream Post labels (Streaming)
Streams all labeling events applied to Posts.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Post labels will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp from which the Post labels will be provided.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `likes_compliance`

Stream Likes compliance data (Streaming)
Streams all compliance data related to Likes for Users.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Likes Compliance events will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp from which the Likes Compliance events will be provided.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `likes_firehose`

Stream all Likes (Streaming)
Streams all public Likes in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Likes will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of LikeWithTweetAuthor fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `likes_sample10`

Stream sampled Likes (Streaming)
Streams a 10% sample of public Likes in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Likes will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of LikeWithTweetAuthor fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts`

Stream filtered Posts (Streaming)
Streams Posts in real-time matching the active rule set.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_compliance`

Stream Posts compliance data (Streaming)
Streams all compliance data related to Posts.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Post Compliance events will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Post Compliance events will be provided.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_firehose`

Stream all Posts (Streaming)
Streams all public Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_firehose_en`

Stream English Posts (Streaming)
Streams all public English-language Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_firehose_ja`

Stream Japanese Posts (Streaming)
Streams all public Japanese-language Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_firehose_ko`

Stream Korean Posts (Streaming)
Streams all public Korean-language Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_firehose_pt`

Stream Portuguese Posts (Streaming)
Streams all public Portuguese-language Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_sample`

Stream sampled Posts (Streaming)
Streams a 1% sample of public Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_sample10`

Stream 10% sampled Posts (Streaming)
Streams a 10% sample of public Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `update_rules`

Update stream rules
Adds or deletes rules from the active rule set for the filtered stream.

#### Parameters

<ParamField type="UpdateRulesRequest">
  Request body
</ParamField>

### `users_compliance`

Stream Users compliance data (Streaming)
Streams all compliance data related to Users.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the User Compliance events will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp from which the User Compliance events will be provided.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>


# StreamClient
Source: https://docs.x.com/xdks/python/reference/xdk.stream.client

Reference for the stream.client Python module in the X API SDK. Client class and methods for calling the stream endpoints of the X API v2.

This module provides a client for interacting with the stream endpoints of the X API.
Real-time streaming operations return generators that yield data as it arrives.
Streaming connections are automatically managed with exponential backoff retry logic for robust handling.

## StreamClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Streaming Client for stream operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get_rule_counts`

Get stream rule counts
Retrieves the count of rules in the active rule set for the filtered stream.

#### Parameters

<ParamField type="List or None">
  A comma separated list of RulesCount fields to display.
</ParamField>

#### Returns

`GetRuleCountsResponse` - Response data

### `get_rules`

Get stream rules
Retrieves the active rule set or a subset of rules for the filtered stream.

#### Parameters

<ParamField type="List or None">
  A comma-separated list of Rule IDs.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="str or None">
  This value is populated by passing the ‘next\_token’ returned in a request to paginate through results.
</ParamField>

#### Returns

`IteratorGetRulesResponse`

### `labels_compliance`

Stream Post labels (Streaming)
Streams all labeling events applied to Posts.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Post labels will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp from which the Post labels will be provided.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `likes_compliance`

Stream Likes compliance data (Streaming)
Streams all compliance data related to Likes for Users.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Likes Compliance events will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp from which the Likes Compliance events will be provided.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `likes_firehose`

Stream all Likes (Streaming)
Streams all public Likes in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Likes will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of LikeWithTweetAuthor fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `likes_sample10`

Stream sampled Likes (Streaming)
Streams a 10% sample of public Likes in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Likes will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of LikeWithTweetAuthor fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts`

Stream filtered Posts (Streaming)
Streams Posts in real-time matching the active rule set.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_compliance`

Stream Posts compliance data (Streaming)
Streams all compliance data related to Posts.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Post Compliance events will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Post Compliance events will be provided.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_firehose`

Stream all Posts (Streaming)
Streams all public Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_firehose_en`

Stream English Posts (Streaming)
Streams all public English-language Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_firehose_ja`

Stream Japanese Posts (Streaming)
Streams all public Japanese-language Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_firehose_ko`

Stream Korean Posts (Streaming)
Streams all public Korean-language Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_firehose_pt`

Stream Portuguese Posts (Streaming)
Streams all public Portuguese-language Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_sample`

Stream sampled Posts (Streaming)
Streams a 1% sample of public Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `posts_sample10`

Stream 10% sampled Posts (Streaming)
Streams a 10% sample of public Posts in real-time.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>

### `update_rules`

Update stream rules
Adds or deletes rules from the active rule set for the filtered stream.

#### Parameters

<ParamField type="UpdateRulesRequest">
  Request body
</ParamField>

### `users_compliance`

Stream Users compliance data (Streaming)
Streams all compliance data related to Users.
This is a streaming endpoint that yields data in real-time as it becomes available.
Each yielded item represents a single data point from the stream.
The connection is automatically managed with exponential backoff retry logic.
If the stream disconnects, the SDK will automatically reconnect without client intervention.

#### Parameters

<ParamField type="int">
  The partition number.
</ParamField>

<ParamField type="int or None">
  The number of minutes of backfill requested.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the User Compliance events will be provided.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp from which the User Compliance events will be provided.
</ParamField>

<ParamField type="StreamConfig">
  Optional StreamConfig for customizing retry behavior, timeouts, and callbacks.
</ParamField>


# Stream.Models
Source: https://docs.x.com/xdks/python/reference/xdk.stream.models

Reference for the stream.models Python module in the X API SDK. Pydantic request and response models for the stream endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the stream endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

## GetRuleCountsResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for get\_rule\_counts

## Methods

### `class xdk.stream.models.GetRuleCountsResponse`

Response model for get\_rule\_counts

### `class xdk.stream.models.GetRulesResponse`

Response model for get\_rules

### `class xdk.stream.models.LabelsComplianceResponse`

Response model for labels\_compliance

### `class xdk.stream.models.LikesComplianceResponse`

Response model for likes\_compliance

### `class xdk.stream.models.LikesFirehoseResponse`

Response model for likes\_firehose

### `class xdk.stream.models.LikesSample10Response`

Response model for likes\_sample10

### `class xdk.stream.models.PostsComplianceResponse`

Response model for posts\_compliance

### `class xdk.stream.models.PostsFirehoseEnResponse`

Response model for posts\_firehose\_en

### `class xdk.stream.models.PostsFirehoseJaResponse`

Response model for posts\_firehose\_ja

### `class xdk.stream.models.PostsFirehoseKoResponse`

Response model for posts\_firehose\_ko

### `class xdk.stream.models.PostsFirehosePtResponse`

Response model for posts\_firehose\_pt

### `class xdk.stream.models.PostsFirehoseResponse`

Response model for posts\_firehose

### `class xdk.stream.models.PostsResponse`

Response model for posts

### `class xdk.stream.models.PostsSample10Response`

Response model for posts\_sample10

### `class xdk.stream.models.PostsSampleResponse`

Response model for posts\_sample

### `class xdk.stream.models.UpdateRulesResponse`

Response model for update\_rules

### `class xdk.stream.models.UsersComplianceResponse`

Response model for users\_compliance


# streaming
Source: https://docs.x.com/xdks/python/reference/xdk.streaming

Reference for the streaming Python package in the X API SDK, grouping the client and Pydantic models for the streaming endpoints of the X API v2.

Robust streaming utilities for the X API SDK.

This module provides streaming connection handling with automatic reconnection,
exponential backoff, and comprehensive error handling. Clients can consume
streaming endpoints without worrying about connection management - the SDK
handles all recovery automatically.

### `class xdk.streaming.StreamConfig`

Configuration for streaming connections with retry behavior.

#### Parameters

<ParamField type="int" />

<ParamField type="float" />

<ParamField type="float" />

<ParamField type="float" />

<ParamField type="bool" />

<ParamField type="float or None" />

<ParamField type="int" />

<ParamField type="Callable[[], None] or None" />

<ParamField type="Callable[[Exception or None], None] or None" />

<ParamField type="Callable[[int, float], None] or None" />

<ParamField type="Callable[[[StreamError" />

### `__init__`

#### Parameters

<ParamField type="int" />

<ParamField type="float" />

<ParamField type="float" />

<ParamField type="float" />

<ParamField type="bool" />

<ParamField type="float or None" />

<ParamField type="int" />

<ParamField type="Callable[[], None] or None" />

<ParamField type="Callable[[Exception or None], None] or None" />

<ParamField type="Callable[[int, float], None] or None" />

<ParamField type="Callable[[[StreamError" />

### `on_error : Callable[[[StreamError]`

### `exception xdk.streaming.StreamError`

Exception raised for streaming errors with classification.

#### Parameters

<ParamField type="str" />

<ParamField type="StreamErrorType" />

### `__init__`

#### Parameters

<ParamField type="str" />

<ParamField type="StreamErrorType" />

### `class xdk.streaming.StreamErrorType`

Classification of streaming errors for retry decisions.

#### Parameters

<ParamField type="Any" />

### `class xdk.streaming.StreamState`

Internal state for a streaming connection.

#### Parameters

<ParamField type="int" />

<ParamField type="float" />

<ParamField type="bool" />

<ParamField type="int" />

<ParamField type="StreamError" />

### `__init__`

#### Parameters

<ParamField type="int" />

<ParamField type="float" />

<ParamField type="bool" />

<ParamField type="int" />

<ParamField type="StreamError" />

### `last_error : [StreamError]`

### `xdk.streaming.stream_with_retry`

Stream data from an endpoint with automatic reconnection and exponential backoff.
This function handles all connection management, including:

* Automatic reconnection on disconnects
* Exponential backoff with jitter for retry delays
* Classification of errors as retryable vs fatal
* Lifecycle callbacks for monitoring connection state

#### Parameters

<ParamField type="Session">
  The requests Session to use for HTTP calls.
</ParamField>

<ParamField type="str">
  HTTP method (typically “get”).
</ParamField>

<ParamField type="str">
  The full URL to stream from.
</ParamField>

<ParamField type="StreamConfig">
  StreamConfig with retry and callback settings.
</ParamField>


# TrendsClient
Source: https://docs.x.com/xdks/python/reference/xdk.trends

Reference for the trends Python package in the X API SDK, grouping the client and Pydantic models for the trends endpoints of the X API v2.

## Submodules

* [xdk.trends.client module](/xdks/python/reference/xdk.trends.client)
  * [`TrendsClient`](/xdks/python/reference/xdk.trends.client#xdk.trends.client.TrendsClient)
    * [`TrendsClient.__init__()`](/xdks/python/reference/xdk.trends.client#xdk.trends.client.TrendsClient.__init__)
    * [`TrendsClient.get_ai()`](/xdks/python/reference/xdk.trends.client#xdk.trends.client.TrendsClient.get_ai)
    * [`TrendsClient.get_by_woeid()`](/xdks/python/reference/xdk.trends.client#xdk.trends.client.TrendsClient.get_by_woeid)
    * [`TrendsClient.get_personalized()`](/xdks/python/reference/xdk.trends.client#xdk.trends.client.TrendsClient.get_personalized)
* [xdk.trends.models module](/xdks/python/reference/xdk.trends.models)
  * [`GetAiResponse`](/xdks/python/reference/xdk.trends.models#xdk.trends.models.GetAiResponse)
    * [`GetAiResponse.model_config`](/xdks/python/reference/xdk.trends.models#xdk.trends.models.GetAiResponse.model_config)
  * [`GetByWoeidResponse`](/xdks/python/reference/xdk.trends.models#xdk.trends.models.GetByWoeidResponse)
    * [`GetByWoeidResponse.model_config`](/xdks/python/reference/xdk.trends.models#xdk.trends.models.GetByWoeidResponse.model_config)
  * [`GetPersonalizedResponse`](/xdks/python/reference/xdk.trends.models#xdk.trends.models.GetPersonalizedResponse)
    * [`GetPersonalizedResponse.model_config`](/xdks/python/reference/xdk.trends.models#xdk.trends.models.GetPersonalizedResponse.model_config)

## Module contents

This module provides access to the trends endpoints of the X API
and serves as the main entry point for all trends-related functionality.

### `class xdk.trends.TrendsClient`

Client for trends operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get_ai`

Get AI Trends by ID
Retrieves an AI trend by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the ai trend.
</ParamField>

<ParamField type="List or None">
  A comma separated list of News fields to display.
</ParamField>

#### Returns

`GetAiResponse` - Response data

### `get_by_woeid`

Get Trends by WOEID
Retrieves trending topics for a specific location identified by its WOEID.

#### Parameters

<ParamField type="int">
  The WOEID of the place to lookup a trend for.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Trend fields to display.
</ParamField>

#### Returns

`GetByWoeidResponse` - Response data

### `get_personalized`

Get personalized Trends
Retrieves personalized trending topics for the authenticated user.

#### Parameters

<ParamField type="List or None">
  A comma separated list of PersonalizedTrend fields to display.
</ParamField>

#### Returns

`GetPersonalizedResponse` - Response data


# TrendsClient
Source: https://docs.x.com/xdks/python/reference/xdk.trends.client

Reference for the trends.client Python module in the X API SDK. Client class and methods for calling the trends endpoints of the X API v2.

## TrendsClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for trends operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get_ai`

Get AI Trends by ID
Retrieves an AI trend by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the ai trend.
</ParamField>

<ParamField type="List or None">
  A comma separated list of News fields to display.
</ParamField>

#### Returns

`GetAiResponse` - Response data

### `get_by_woeid`

Get Trends by WOEID
Retrieves trending topics for a specific location identified by its WOEID.

#### Parameters

<ParamField type="int">
  The WOEID of the place to lookup a trend for.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Trend fields to display.
</ParamField>

#### Returns

`GetByWoeidResponse` - Response data

### `get_personalized`

Get personalized Trends
Retrieves personalized trending topics for the authenticated user.

#### Parameters

<ParamField type="List or None">
  A comma separated list of PersonalizedTrend fields to display.
</ParamField>

#### Returns

`GetPersonalizedResponse` - Response data


# Trends.Models
Source: https://docs.x.com/xdks/python/reference/xdk.trends.models

Reference for the trends.models Python module in the X API SDK. Pydantic request and response models for the trends endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the trends endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

## GetAiResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for get\_ai

## Methods

### `class xdk.trends.models.GetAiResponse`

Response model for get\_ai

### `class xdk.trends.models.GetByWoeidResponse`

Response model for get\_by\_woeid

### `class xdk.trends.models.GetPersonalizedResponse`

Response model for get\_personalized


# UsageClient
Source: https://docs.x.com/xdks/python/reference/xdk.usage

Reference for the usage Python package in the X API SDK, grouping the client and Pydantic models for the usage endpoints of the X API v2.

## Submodules

* [xdk.usage.client module](/xdks/python/reference/xdk.usage.client)
  * [`UsageClient`](/xdks/python/reference/xdk.usage.client#xdk.usage.client.UsageClient)
    * [`UsageClient.__init__()`](/xdks/python/reference/xdk.usage.client#xdk.usage.client.UsageClient.__init__)
    * [`UsageClient.get()`](/xdks/python/reference/xdk.usage.client#xdk.usage.client.UsageClient.get)
* [xdk.usage.models module](/xdks/python/reference/xdk.usage.models)
  * [`GetResponse`](/xdks/python/reference/xdk.usage.models#xdk.usage.models.GetResponse)
    * [`GetResponse.model_config`](/xdks/python/reference/xdk.usage.models#xdk.usage.models.GetResponse.model_config)

## Module contents

This module provides access to the usage endpoints of the X API
and serves as the main entry point for all usage-related functionality.

### `class xdk.usage.UsageClient`

Client for usage operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get`

Get usage
Retrieves usage statistics for Posts over a specified number of days.

#### Parameters

<ParamField type="int or None">
  The number of days for which you need usage for.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Usage fields to display.
</ParamField>

#### Returns

`GetResponse` - Response data


# UsageClient
Source: https://docs.x.com/xdks/python/reference/xdk.usage.client

Reference for the usage.client Python module in the X API SDK. Client class and methods for calling the usage endpoints of the X API v2.

## UsageClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for usage operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `get`

Get usage
Retrieves usage statistics for Posts over a specified number of days.

#### Parameters

<ParamField type="int or None">
  The number of days for which you need usage for.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Usage fields to display.
</ParamField>

#### Returns

`GetResponse` - Response data


# Usage.Models
Source: https://docs.x.com/xdks/python/reference/xdk.usage.models

Reference for the usage.models Python module in the X API SDK. Pydantic request and response models for the usage endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the usage endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

## GetResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for get

## Methods

### `class xdk.usage.models.GetResponse`

Response model for get


# UsersClient
Source: https://docs.x.com/xdks/python/reference/xdk.users

Reference for the users Python package in the X API SDK, grouping the client and Pydantic models for the users endpoints of the X API v2.

## Submodules

* [xdk.users.client module](/xdks/python/reference/xdk.users.client)
  * [`UsersClient`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient)
    * [`UsersClient.__init__()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.__init__)
    * [`UsersClient.block_dms()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.block_dms)
    * [`UsersClient.create_bookmark()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.create_bookmark)
    * [`UsersClient.delete_bookmark()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.delete_bookmark)
    * [`UsersClient.follow_list()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.follow_list)
    * [`UsersClient.follow_user()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.follow_user)
    * [`UsersClient.get_blocking()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_blocking)
    * [`UsersClient.get_bookmark_folders()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_bookmark_folders)
    * [`UsersClient.get_bookmarks()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_bookmarks)
    * [`UsersClient.get_bookmarks_by_folder_id()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_bookmarks_by_folder_id)
    * [`UsersClient.get_by_id()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_by_id)
    * [`UsersClient.get_by_ids()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_by_ids)
    * [`UsersClient.get_by_username()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_by_username)
    * [`UsersClient.get_by_usernames()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_by_usernames)
    * [`UsersClient.get_followed_lists()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_followed_lists)
    * [`UsersClient.get_followers()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_followers)
    * [`UsersClient.get_following()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_following)
    * [`UsersClient.get_liked_posts()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_liked_posts)
    * [`UsersClient.get_list_memberships()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_list_memberships)
    * [`UsersClient.get_me()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_me)
    * [`UsersClient.get_mentions()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_mentions)
    * [`UsersClient.get_muting()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_muting)
    * [`UsersClient.get_owned_lists()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_owned_lists)
    * [`UsersClient.get_pinned_lists()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_pinned_lists)
    * [`UsersClient.get_posts()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_posts)
    * [`UsersClient.get_reposts_of_me()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_reposts_of_me)
    * [`UsersClient.get_timeline()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.get_timeline)
    * [`UsersClient.like_post()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.like_post)
    * [`UsersClient.mute_user()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.mute_user)
    * [`UsersClient.pin_list()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.pin_list)
    * [`UsersClient.repost_post()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.repost_post)
    * [`UsersClient.search()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.search)
    * [`UsersClient.unblock_dms()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.unblock_dms)
    * [`UsersClient.unfollow_list()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.unfollow_list)
    * [`UsersClient.unfollow_user()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.unfollow_user)
    * [`UsersClient.unlike_post()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.unlike_post)
    * [`UsersClient.unmute_user()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.unmute_user)
    * [`UsersClient.unpin_list()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.unpin_list)
    * [`UsersClient.unrepost_post()`](/xdks/python/reference/xdk.users.client#xdk.users.client.UsersClient.unrepost_post)
* [xdk.users.models module](/xdks/python/reference/xdk.users.models)
  * [`BlockDmsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.BlockDmsResponse)
    * [`BlockDmsResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.BlockDmsResponse.model_config)
  * [`CreateBookmarkRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.CreateBookmarkRequest)
    * [`CreateBookmarkRequest.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.CreateBookmarkRequest.model_config)
  * [`CreateBookmarkResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.CreateBookmarkResponse)
    * [`CreateBookmarkResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.CreateBookmarkResponse.model_config)
  * [`DeleteBookmarkResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.DeleteBookmarkResponse)
    * [`DeleteBookmarkResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.DeleteBookmarkResponse.model_config)
  * [`FollowListRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.FollowListRequest)
    * [`FollowListRequest.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.FollowListRequest.model_config)
  * [`FollowListResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.FollowListResponse)
    * [`FollowListResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.FollowListResponse.model_config)
  * [`FollowUserRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.FollowUserRequest)
    * [`FollowUserRequest.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.FollowUserRequest.model_config)
  * [`FollowUserResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.FollowUserResponse)
    * [`FollowUserResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.FollowUserResponse.model_config)
  * [`GetBlockingResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetBlockingResponse)
    * [`GetBlockingResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetBlockingResponse.model_config)
  * [`GetBookmarkFoldersResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetBookmarkFoldersResponse)
    * [`GetBookmarkFoldersResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetBookmarkFoldersResponse.model_config)
  * [`GetBookmarksByFolderIdResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetBookmarksByFolderIdResponse)
    * [`GetBookmarksByFolderIdResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetBookmarksByFolderIdResponse.model_config)
  * [`GetBookmarksResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetBookmarksResponse)
    * [`GetBookmarksResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetBookmarksResponse.model_config)
  * [`GetByIdResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetByIdResponse)
    * [`GetByIdResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetByIdResponse.model_config)
  * [`GetByIdsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetByIdsResponse)
    * [`GetByIdsResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetByIdsResponse.model_config)
  * [`GetByUsernameResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetByUsernameResponse)
    * [`GetByUsernameResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetByUsernameResponse.model_config)
  * [`GetByUsernamesResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetByUsernamesResponse)
    * [`GetByUsernamesResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetByUsernamesResponse.model_config)
  * [`GetFollowedListsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetFollowedListsResponse)
    * [`GetFollowedListsResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetFollowedListsResponse.model_config)
  * [`GetFollowersResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetFollowersResponse)
    * [`GetFollowersResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetFollowersResponse.model_config)
  * [`GetFollowingResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetFollowingResponse)
    * [`GetFollowingResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetFollowingResponse.model_config)
  * [`GetLikedPostsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetLikedPostsResponse)
    * [`GetLikedPostsResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetLikedPostsResponse.model_config)
  * [`GetListMembershipsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetListMembershipsResponse)
    * [`GetListMembershipsResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetListMembershipsResponse.model_config)
  * [`GetMeResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetMeResponse)
    * [`GetMeResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetMeResponse.model_config)
  * [`GetMentionsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetMentionsResponse)
    * [`GetMentionsResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetMentionsResponse.model_config)
  * [`GetMutingResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetMutingResponse)
    * [`GetMutingResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetMutingResponse.model_config)
  * [`GetOwnedListsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetOwnedListsResponse)
    * [`GetOwnedListsResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetOwnedListsResponse.model_config)
  * [`GetPinnedListsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetPinnedListsResponse)
    * [`GetPinnedListsResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetPinnedListsResponse.model_config)
  * [`GetPostsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetPostsResponse)
    * [`GetPostsResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetPostsResponse.model_config)
  * [`GetRepostsOfMeResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetRepostsOfMeResponse)
    * [`GetRepostsOfMeResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetRepostsOfMeResponse.model_config)
  * [`GetTimelineResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetTimelineResponse)
    * [`GetTimelineResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.GetTimelineResponse.model_config)
  * [`LikePostRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.LikePostRequest)
    * [`LikePostRequest.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.LikePostRequest.model_config)
  * [`LikePostResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.LikePostResponse)
    * [`LikePostResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.LikePostResponse.model_config)
  * [`MuteUserRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.MuteUserRequest)
    * [`MuteUserRequest.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.MuteUserRequest.model_config)
  * [`MuteUserResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.MuteUserResponse)
    * [`MuteUserResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.MuteUserResponse.model_config)
  * [`PinListRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.PinListRequest)
    * [`PinListRequest.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.PinListRequest.model_config)
  * [`PinListResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.PinListResponse)
    * [`PinListResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.PinListResponse.model_config)
  * [`RepostPostRequest`](/xdks/python/reference/xdk.users.models#xdk.users.models.RepostPostRequest)
    * [`RepostPostRequest.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.RepostPostRequest.model_config)
  * [`RepostPostResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.RepostPostResponse)
    * [`RepostPostResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.RepostPostResponse.model_config)
  * [`SearchResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.SearchResponse)
    * [`SearchResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.SearchResponse.model_config)
  * [`UnblockDmsResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnblockDmsResponse)
    * [`UnblockDmsResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnblockDmsResponse.model_config)
  * [`UnfollowListResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnfollowListResponse)
    * [`UnfollowListResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnfollowListResponse.model_config)
  * [`UnfollowUserResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnfollowUserResponse)
    * [`UnfollowUserResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnfollowUserResponse.model_config)
  * [`UnlikePostResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnlikePostResponse)
    * [`UnlikePostResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnlikePostResponse.model_config)
  * [`UnmuteUserResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnmuteUserResponse)
    * [`UnmuteUserResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnmuteUserResponse.model_config)
  * [`UnpinListResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnpinListResponse)
    * [`UnpinListResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnpinListResponse.model_config)
  * [`UnrepostPostResponse`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnrepostPostResponse)
    * [`UnrepostPostResponse.model_config`](/xdks/python/reference/xdk.users.models#xdk.users.models.UnrepostPostResponse.model_config)

## Module contents

This module provides access to the users endpoints of the X API
and serves as the main entry point for all users-related functionality.

### `class xdk.users.UsersClient`

Client for users operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `block_dms`

Block DMs
Blocks direct messages to or from a specific User by their ID for the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the target User that the authenticated user requesting to block dms for.
</ParamField>

#### Returns

`BlockDmsResponse` - Response data

### `create_bookmark`

Create Bookmark
Adds a post to the authenticated user’s bookmarks.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to add bookmarks.
</ParamField>

<ParamField type="CreateBookmarkRequest">
  Request body
</ParamField>

### `delete_bookmark`

Delete Bookmark
Removes a Post from the authenticated user’s Bookmarks by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User whose bookmark is to be removed.
</ParamField>

<ParamField type="Any">
  The ID of the Post that the source User is removing from bookmarks.
</ParamField>

#### Returns

`DeleteBookmarkResponse` - Response data

### `follow_list`

Follow List
Causes the authenticated user to follow a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that will follow the List.
</ParamField>

<ParamField type="FollowListRequest">
  Request body
</ParamField>

### `follow_user`

Follow User
Causes the authenticated user to follow a specific user by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to follow the target User.
</ParamField>

<ParamField type="FollowUserRequest">
  Request body
</ParamField>

### `get_blocking`

Get blocking
Retrieves a list of Users blocked by the specified User ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetBlockingResponse`

### `get_bookmark_folders`

Get Bookmark folders
Retrieves a list of Bookmark folders created by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

#### Returns

`IteratorGetBookmarkFoldersResponse`

### `get_bookmarks`

Get Bookmarks
Retrieves a list of Posts bookmarked by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetBookmarksResponse`

### `get_bookmarks_by_folder_id`

Get Bookmarks by folder ID
Retrieves Posts in a specific Bookmark folder by its ID for the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="Any">
  The ID of the Bookmark Folder that the authenticated User is trying to fetch Posts for.
</ParamField>

#### Returns

`GetBookmarksByFolderIdResponse` - Response data

### `get_by_id`

Get User by ID
Retrieves details of a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`GetByIdResponse` - Response data

### `get_by_ids`

Get Users by IDs
Retrieves details of multiple Users by their IDs.

#### Parameters

<ParamField type="List">
  A list of User IDs, comma-separated. You can specify up to 100 IDs.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`GetByIdsResponse` - Response data

### `get_by_username`

Get User by username
Retrieves details of a specific User by their username.

#### Parameters

<ParamField type="str">
  A username.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`GetByUsernameResponse` - Response data

### `get_by_usernames`

Get Users by usernames
Retrieves details of multiple Users by their usernames.

#### Parameters

<ParamField type="List">
  A list of usernames, comma-separated.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`GetByUsernamesResponse` - Response data

### `get_followed_lists`

Get followed Lists
Retrieves a list of Lists followed by a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of List fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

#### Returns

`IteratorGetFollowedListsResponse`

### `get_followers`

Get followers
Retrieves a list of Users who follow a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetFollowersResponse`

### `get_following`

Get following
Retrieves a list of Users followed by a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetFollowingResponse`

### `get_liked_posts`

Get liked Posts
Retrieves a list of Posts liked by a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetLikedPostsResponse`

### `get_list_memberships`

Get List memberships
Retrieves a list of Lists that a specific User is a member of by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of List fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

#### Returns

`IteratorGetListMembershipsResponse`

### `get_me`

Get my User
Retrieves details of the authenticated user.

#### Parameters

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`GetMeResponse` - Response data

### `get_mentions`

Get mentions
Retrieves a list of Posts that mention a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="Any or None">
  The minimum Post ID to be included in the result set. This parameter takes precedence over start\_time if both are specified.
</ParamField>

<ParamField type="Any or None">
  The maximum Post ID to be included in the result set. This parameter takes precedence over end\_time if both are specified.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Posts will be provided. The since\_id parameter takes precedence if it is also specified.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided. The until\_id parameter takes precedence if it is also specified.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetMentionsResponse`

### `get_muting`

Get muting
Retrieves a list of Users muted by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetMutingResponse`

### `get_owned_lists`

Get owned Lists
Retrieves a list of Lists owned by a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of List fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

#### Returns

`IteratorGetOwnedListsResponse`

### `get_pinned_lists`

Get pinned Lists
Retrieves a list of Lists pinned by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of List fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

#### Returns

`GetPinnedListsResponse` - Response data

### `get_posts`

Get Posts
Retrieves a list of posts authored by a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="Any or None">
  The minimum Post ID to be included in the result set. This parameter takes precedence over start\_time if both are specified.
</ParamField>

<ParamField type="Any or None">
  The maximum Post ID to be included in the result set. This parameter takes precedence over end\_time if both are specified.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  The set of entities to exclude (e.g. ‘replies’ or ‘retweets’).
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Posts will be provided. The since\_id parameter takes precedence if it is also specified.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided. The until\_id parameter takes precedence if it is also specified.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetPostsResponse`

### `get_reposts_of_me`

Get Reposts of me
Retrieves a list of Posts that repost content from the authenticated user.

#### Parameters

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetRepostsOfMeResponse`

### `get_timeline`

Get Timeline
Retrieves a reverse chronological list of Posts in the authenticated User’s Timeline.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User to list Reverse Chronological Timeline Posts of.
</ParamField>

<ParamField type="Any or None">
  The minimum Post ID to be included in the result set. This parameter takes precedence over start\_time if both are specified.
</ParamField>

<ParamField type="Any or None">
  The maximum Post ID to be included in the result set. This parameter takes precedence over end\_time if both are specified.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  The set of entities to exclude (e.g. ‘replies’ or ‘retweets’).
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Posts will be provided. The since\_id parameter takes precedence if it is also specified.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided. The until\_id parameter takes precedence if it is also specified.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetTimelineResponse`

### `like_post`

Like Post
Causes the authenticated user to Like a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to like the Post.
</ParamField>

<ParamField type="LikePostRequest">
  Request body
</ParamField>

### `mute_user`

Mute User
Causes the authenticated user to mute a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to mute the target User.
</ParamField>

<ParamField type="MuteUserRequest">
  Request body
</ParamField>

### `pin_list`

Pin List
Causes the authenticated user to pin a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that will pin the List.
</ParamField>

<ParamField type="PinListRequest">
  Request body
</ParamField>

### `repost_post`

Repost Post
Causes the authenticated user to repost a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to repost the Post.
</ParamField>

<ParamField type="RepostPostRequest">
  Request body
</ParamField>

### `search`

Search Users
Retrieves a list of Users matching a search query.

#### Parameters

<ParamField type="Any">
  TThe the query string by which to query for users.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorSearchResponse`

### `unblock_dms`

Unblock DMs
Unblocks direct messages to or from a specific User by their ID for the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the target User that the authenticated user requesting to unblock dms for.
</ParamField>

#### Returns

`UnblockDmsResponse` - Response data

### `unfollow_list`

Unfollow List
Causes the authenticated user to unfollow a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that will unfollow the List.
</ParamField>

<ParamField type="Any">
  The ID of the List to unfollow.
</ParamField>

#### Returns

`UnfollowListResponse` - Response data

### `unfollow_user`

Unfollow User
Causes the authenticated user to unfollow a specific user by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to unfollow the target User.
</ParamField>

<ParamField type="Any">
  The ID of the User that the source User is requesting to unfollow.
</ParamField>

#### Returns

`UnfollowUserResponse` - Response data

### `unlike_post`

Unlike Post
Causes the authenticated user to Unlike a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to unlike the Post.
</ParamField>

<ParamField type="Any">
  The ID of the Post that the User is requesting to unlike.
</ParamField>

#### Returns

`UnlikePostResponse` - Response data

### `unmute_user`

Unmute User
Causes the authenticated user to unmute a specific user by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to unmute the target User.
</ParamField>

<ParamField type="Any">
  The ID of the User that the source User is requesting to unmute.
</ParamField>

#### Returns

`UnmuteUserResponse` - Response data

### `unpin_list`

Unpin List
Causes the authenticated user to unpin a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="Any">
  The ID of the List to unpin.
</ParamField>

#### Returns

`UnpinListResponse` - Response data

### `unrepost_post`

Unrepost Post
Causes the authenticated user to unrepost a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to repost the Post.
</ParamField>

<ParamField type="Any">
  The ID of the Post that the User is requesting to unretweet.
</ParamField>

#### Returns

`UnrepostPostResponse` - Response data


# UsersClient
Source: https://docs.x.com/xdks/python/reference/xdk.users.client

Reference for the users.client Python module in the X API SDK. Client class and methods for calling the users endpoints of the X API v2.

## UsersClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for users operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `block_dms`

Block DMs
Blocks direct messages to or from a specific User by their ID for the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the target User that the authenticated user requesting to block dms for.
</ParamField>

#### Returns

`BlockDmsResponse` - Response data

### `create_bookmark`

Create Bookmark
Adds a post to the authenticated user’s bookmarks.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to add bookmarks.
</ParamField>

<ParamField type="CreateBookmarkRequest">
  Request body
</ParamField>

### `delete_bookmark`

Delete Bookmark
Removes a Post from the authenticated user’s Bookmarks by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User whose bookmark is to be removed.
</ParamField>

<ParamField type="Any">
  The ID of the Post that the source User is removing from bookmarks.
</ParamField>

#### Returns

`DeleteBookmarkResponse` - Response data

### `follow_list`

Follow List
Causes the authenticated user to follow a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that will follow the List.
</ParamField>

<ParamField type="FollowListRequest">
  Request body
</ParamField>

### `follow_user`

Follow User
Causes the authenticated user to follow a specific user by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to follow the target User.
</ParamField>

<ParamField type="FollowUserRequest">
  Request body
</ParamField>

### `get_blocking`

Get blocking
Retrieves a list of Users blocked by the specified User ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetBlockingResponse`

### `get_bookmark_folders`

Get Bookmark folders
Retrieves a list of Bookmark folders created by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

#### Returns

`IteratorGetBookmarkFoldersResponse`

### `get_bookmarks`

Get Bookmarks
Retrieves a list of Posts bookmarked by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetBookmarksResponse`

### `get_bookmarks_by_folder_id`

Get Bookmarks by folder ID
Retrieves Posts in a specific Bookmark folder by its ID for the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="Any">
  The ID of the Bookmark Folder that the authenticated User is trying to fetch Posts for.
</ParamField>

#### Returns

`GetBookmarksByFolderIdResponse` - Response data

### `get_by_id`

Get User by ID
Retrieves details of a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`GetByIdResponse` - Response data

### `get_by_ids`

Get Users by IDs
Retrieves details of multiple Users by their IDs.

#### Parameters

<ParamField type="List">
  A list of User IDs, comma-separated. You can specify up to 100 IDs.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`GetByIdsResponse` - Response data

### `get_by_username`

Get User by username
Retrieves details of a specific User by their username.

#### Parameters

<ParamField type="str">
  A username.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`GetByUsernameResponse` - Response data

### `get_by_usernames`

Get Users by usernames
Retrieves details of multiple Users by their usernames.

#### Parameters

<ParamField type="List">
  A list of usernames, comma-separated.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`GetByUsernamesResponse` - Response data

### `get_followed_lists`

Get followed Lists
Retrieves a list of Lists followed by a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of List fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

#### Returns

`IteratorGetFollowedListsResponse`

### `get_followers`

Get followers
Retrieves a list of Users who follow a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetFollowersResponse`

### `get_following`

Get following
Retrieves a list of Users followed by a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetFollowingResponse`

### `get_liked_posts`

Get liked Posts
Retrieves a list of Posts liked by a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetLikedPostsResponse`

### `get_list_memberships`

Get List memberships
Retrieves a list of Lists that a specific User is a member of by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of List fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

#### Returns

`IteratorGetListMembershipsResponse`

### `get_me`

Get my User
Retrieves details of the authenticated user.

#### Parameters

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`GetMeResponse` - Response data

### `get_mentions`

Get mentions
Retrieves a list of Posts that mention a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="Any or None">
  The minimum Post ID to be included in the result set. This parameter takes precedence over start\_time if both are specified.
</ParamField>

<ParamField type="Any or None">
  The maximum Post ID to be included in the result set. This parameter takes precedence over end\_time if both are specified.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Posts will be provided. The since\_id parameter takes precedence if it is also specified.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided. The until\_id parameter takes precedence if it is also specified.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetMentionsResponse`

### `get_muting`

Get muting
Retrieves a list of Users muted by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorGetMutingResponse`

### `get_owned_lists`

Get owned Lists
Retrieves a list of Lists owned by a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get a specified ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of List fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

#### Returns

`IteratorGetOwnedListsResponse`

### `get_pinned_lists`

Get pinned Lists
Retrieves a list of Lists pinned by the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of List fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

#### Returns

`GetPinnedListsResponse` - Response data

### `get_posts`

Get Posts
Retrieves a list of posts authored by a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the User to lookup.
</ParamField>

<ParamField type="Any or None">
  The minimum Post ID to be included in the result set. This parameter takes precedence over start\_time if both are specified.
</ParamField>

<ParamField type="Any or None">
  The maximum Post ID to be included in the result set. This parameter takes precedence over end\_time if both are specified.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  The set of entities to exclude (e.g. ‘replies’ or ‘retweets’).
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Posts will be provided. The since\_id parameter takes precedence if it is also specified.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided. The until\_id parameter takes precedence if it is also specified.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetPostsResponse`

### `get_reposts_of_me`

Get Reposts of me
Retrieves a list of Posts that repost content from the authenticated user.

#### Parameters

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetRepostsOfMeResponse`

### `get_timeline`

Get Timeline
Retrieves a reverse chronological list of Posts in the authenticated User’s Timeline.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User to list Reverse Chronological Timeline Posts of.
</ParamField>

<ParamField type="Any or None">
  The minimum Post ID to be included in the result set. This parameter takes precedence over start\_time if both are specified.
</ParamField>

<ParamField type="Any or None">
  The maximum Post ID to be included in the result set. This parameter takes precedence over end\_time if both are specified.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results.
</ParamField>

<ParamField type="List or None">
  The set of entities to exclude (e.g. ‘replies’ or ‘retweets’).
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Posts will be provided. The since\_id parameter takes precedence if it is also specified.
</ParamField>

<ParamField type="str or None">
  YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided. The until\_id parameter takes precedence if it is also specified.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`IteratorGetTimelineResponse`

### `like_post`

Like Post
Causes the authenticated user to Like a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to like the Post.
</ParamField>

<ParamField type="LikePostRequest">
  Request body
</ParamField>

### `mute_user`

Mute User
Causes the authenticated user to mute a specific User by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to mute the target User.
</ParamField>

<ParamField type="MuteUserRequest">
  Request body
</ParamField>

### `pin_list`

Pin List
Causes the authenticated user to pin a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that will pin the List.
</ParamField>

<ParamField type="PinListRequest">
  Request body
</ParamField>

### `repost_post`

Repost Post
Causes the authenticated user to repost a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to repost the Post.
</ParamField>

<ParamField type="RepostPostRequest">
  Request body
</ParamField>

### `search`

Search Users
Retrieves a list of Users matching a search query.

#### Parameters

<ParamField type="Any">
  TThe the query string by which to query for users.
</ParamField>

<ParamField type="int or None">
  The maximum number of results.
</ParamField>

<ParamField type="Any or None">
  This parameter is used to get the next ‘page’ of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
</ParamField>

<ParamField type="List or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="List or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="List or None">
  A comma separated list of Tweet fields to display.
</ParamField>

#### Returns

`IteratorSearchResponse`

### `unblock_dms`

Unblock DMs
Unblocks direct messages to or from a specific User by their ID for the authenticated user.

#### Parameters

<ParamField type="Any">
  The ID of the target User that the authenticated user requesting to unblock dms for.
</ParamField>

#### Returns

`UnblockDmsResponse` - Response data

### `unfollow_list`

Unfollow List
Causes the authenticated user to unfollow a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that will unfollow the List.
</ParamField>

<ParamField type="Any">
  The ID of the List to unfollow.
</ParamField>

#### Returns

`UnfollowListResponse` - Response data

### `unfollow_user`

Unfollow User
Causes the authenticated user to unfollow a specific user by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to unfollow the target User.
</ParamField>

<ParamField type="Any">
  The ID of the User that the source User is requesting to unfollow.
</ParamField>

#### Returns

`UnfollowUserResponse` - Response data

### `unlike_post`

Unlike Post
Causes the authenticated user to Unlike a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to unlike the Post.
</ParamField>

<ParamField type="Any">
  The ID of the Post that the User is requesting to unlike.
</ParamField>

#### Returns

`UnlikePostResponse` - Response data

### `unmute_user`

Unmute User
Causes the authenticated user to unmute a specific user by their ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to unmute the target User.
</ParamField>

<ParamField type="Any">
  The ID of the User that the source User is requesting to unmute.
</ParamField>

#### Returns

`UnmuteUserResponse` - Response data

### `unpin_list`

Unpin List
Causes the authenticated user to unpin a specific List by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User for whom to return results.
</ParamField>

<ParamField type="Any">
  The ID of the List to unpin.
</ParamField>

#### Returns

`UnpinListResponse` - Response data

### `unrepost_post`

Unrepost Post
Causes the authenticated user to unrepost a specific Post by its ID.

#### Parameters

<ParamField type="Any">
  The ID of the authenticated source User that is requesting to repost the Post.
</ParamField>

<ParamField type="Any">
  The ID of the Post that the User is requesting to unretweet.
</ParamField>

#### Returns

`UnrepostPostResponse` - Response data


# Users.Models
Source: https://docs.x.com/xdks/python/reference/xdk.users.models

Reference for the users.models Python module in the X API SDK. Pydantic request and response models for the users endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the users endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

## BlockDmsResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for block\_dms

## Methods

### `class xdk.users.models.BlockDmsResponse`

Response model for block\_dms

### `class xdk.users.models.CreateBookmarkResponse`

Response model for create\_bookmark

### `class xdk.users.models.DeleteBookmarkResponse`

Response model for delete\_bookmark

### `class xdk.users.models.FollowListResponse`

Response model for follow\_list

### `class xdk.users.models.FollowUserResponse`

Response model for follow\_user

### `class xdk.users.models.GetBlockingResponse`

Response model for get\_blocking

### `class xdk.users.models.GetBookmarkFoldersResponse`

Response model for get\_bookmark\_folders

### `class xdk.users.models.GetBookmarksByFolderIdResponse`

Response model for get\_bookmarks\_by\_folder\_id

### `class xdk.users.models.GetBookmarksResponse`

Response model for get\_bookmarks

### `class xdk.users.models.GetByIdResponse`

Response model for get\_by\_id

### `class xdk.users.models.GetByIdsResponse`

Response model for get\_by\_ids

### `class xdk.users.models.GetByUsernameResponse`

Response model for get\_by\_username

### `class xdk.users.models.GetByUsernamesResponse`

Response model for get\_by\_usernames

### `class xdk.users.models.GetFollowedListsResponse`

Response model for get\_followed\_lists

### `class xdk.users.models.GetFollowersResponse`

Response model for get\_followers

### `class xdk.users.models.GetFollowingResponse`

Response model for get\_following

### `class xdk.users.models.GetLikedPostsResponse`

Response model for get\_liked\_posts

### `class xdk.users.models.GetListMembershipsResponse`

Response model for get\_list\_memberships

### `class xdk.users.models.GetMeResponse`

Response model for get\_me

### `class xdk.users.models.GetMentionsResponse`

Response model for get\_mentions

### `class xdk.users.models.GetMutingResponse`

Response model for get\_muting

### `class xdk.users.models.GetOwnedListsResponse`

Response model for get\_owned\_lists

### `class xdk.users.models.GetPinnedListsResponse`

Response model for get\_pinned\_lists

### `class xdk.users.models.GetPostsResponse`

Response model for get\_posts

### `class xdk.users.models.GetRepostsOfMeResponse`

Response model for get\_reposts\_of\_me

### `class xdk.users.models.GetTimelineResponse`

Response model for get\_timeline

### `class xdk.users.models.LikePostResponse`

Response model for like\_post

### `class xdk.users.models.MuteUserResponse`

Response model for mute\_user

### `class xdk.users.models.PinListResponse`

Response model for pin\_list

### `class xdk.users.models.RepostPostResponse`

Response model for repost\_post

### `class xdk.users.models.SearchResponse`

Response model for search

### `class xdk.users.models.UnblockDmsResponse`

Response model for unblock\_dms

### `class xdk.users.models.UnfollowListResponse`

Response model for unfollow\_list

### `class xdk.users.models.UnfollowUserResponse`

Response model for unfollow\_user

### `class xdk.users.models.UnlikePostResponse`

Response model for unlike\_post

### `class xdk.users.models.UnmuteUserResponse`

Response model for unmute\_user

### `class xdk.users.models.UnpinListResponse`

Response model for unpin\_list

### `class xdk.users.models.UnrepostPostResponse`

Response model for unrepost\_post


# WebhooksClient
Source: https://docs.x.com/xdks/python/reference/xdk.webhooks

Reference for the webhooks Python package in the X API SDK, grouping the client and Pydantic models for the webhooks endpoints of the X API v2.

## Submodules

* [xdk.webhooks.client module](/xdks/python/reference/xdk.webhooks.client)
  * [`WebhooksClient`](/xdks/python/reference/xdk.webhooks.client#xdk.webhooks.client.WebhooksClient)
    * [`WebhooksClient.__init__()`](/xdks/python/reference/xdk.webhooks.client#xdk.webhooks.client.WebhooksClient.__init__)
    * [`WebhooksClient.create()`](/xdks/python/reference/xdk.webhooks.client#xdk.webhooks.client.WebhooksClient.create)
    * [`WebhooksClient.create_stream_link()`](/xdks/python/reference/xdk.webhooks.client#xdk.webhooks.client.WebhooksClient.create_stream_link)
    * [`WebhooksClient.create_webhook_replay_job()`](/xdks/python/reference/xdk.webhooks.client#xdk.webhooks.client.WebhooksClient.create_webhook_replay_job)
    * [`WebhooksClient.delete()`](/xdks/python/reference/xdk.webhooks.client#xdk.webhooks.client.WebhooksClient.delete)
    * [`WebhooksClient.delete_stream_link()`](/xdks/python/reference/xdk.webhooks.client#xdk.webhooks.client.WebhooksClient.delete_stream_link)
    * [`WebhooksClient.get()`](/xdks/python/reference/xdk.webhooks.client#xdk.webhooks.client.WebhooksClient.get)
    * [`WebhooksClient.get_stream_links()`](/xdks/python/reference/xdk.webhooks.client#xdk.webhooks.client.WebhooksClient.get_stream_links)
    * [`WebhooksClient.validate()`](/xdks/python/reference/xdk.webhooks.client#xdk.webhooks.client.WebhooksClient.validate)
* [xdk.webhooks.models module](/xdks/python/reference/xdk.webhooks.models)
  * [`CreateRequest`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateRequest)
    * [`CreateRequest.model_config`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateRequest.model_config)
  * [`CreateResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateResponse)
    * [`CreateResponse.model_config`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateResponse.model_config)
  * [`CreateStreamLinkResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateStreamLinkResponse)
    * [`CreateStreamLinkResponse.model_config`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateStreamLinkResponse.model_config)
  * [`CreateWebhookReplayJobRequest`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateWebhookReplayJobRequest)
    * [`CreateWebhookReplayJobRequest.model_config`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateWebhookReplayJobRequest.model_config)
  * [`CreateWebhookReplayJobResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateWebhookReplayJobResponse)
    * [`CreateWebhookReplayJobResponse.model_config`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.CreateWebhookReplayJobResponse.model_config)
  * [`DeleteResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.DeleteResponse)
    * [`DeleteResponse.model_config`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.DeleteResponse.model_config)
  * [`DeleteStreamLinkResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.DeleteStreamLinkResponse)
    * [`DeleteStreamLinkResponse.model_config`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.DeleteStreamLinkResponse.model_config)
  * [`GetResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.GetResponse)
    * [`GetResponse.model_config`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.GetResponse.model_config)
  * [`GetStreamLinksResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.GetStreamLinksResponse)
    * [`GetStreamLinksResponse.model_config`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.GetStreamLinksResponse.model_config)
  * [`ValidateResponse`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.ValidateResponse)
    * [`ValidateResponse.model_config`](/xdks/python/reference/xdk.webhooks.models#xdk.webhooks.models.ValidateResponse.model_config)

## Module contents

This module provides access to the webhooks endpoints of the X API
and serves as the main entry point for all webhooks-related functionality.

### `class xdk.webhooks.WebhooksClient`

Client for webhooks operations

#### Parameters

<ParamField type="Client" />

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create`

Create webhook
Creates a new webhook configuration.
body: Request body
:returns: Response data
:rtype: CreateResponse

#### Parameters

<ParamField type="CreateRequest" />

### `create_stream_link`

Create stream link
Creates a link to deliver FilteredStream events to the given webhook.

#### Parameters

<ParamField type="Any">
  The webhook ID to link to your FilteredStream ruleset.
</ParamField>

<ParamField type="str or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="str or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="str or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="str or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="str or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="str or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`CreateStreamLinkResponse` - Response data

### `create_webhook_replay_job`

Create replay job for webhook
Creates a replay job to retrieve events from up to the past 24 hours for all events delivered or attempted to be delivered to the webhook.
body: Request body
:returns: Response data
:rtype: CreateWebhookReplayJobResponse

#### Parameters

<ParamField type="CreateWebhookReplayJobRequest" />

### `delete`

Delete webhook
Deletes an existing webhook configuration.

#### Parameters

<ParamField type="Any">
  The ID of the webhook to delete.
</ParamField>

#### Returns

`DeleteResponse` - Response data

### `delete_stream_link`

Delete stream link
Deletes a link from FilteredStream events to the given webhook.

#### Parameters

<ParamField type="Any">
  The webhook ID to link to your FilteredStream ruleset.
</ParamField>

#### Returns

`DeleteStreamLinkResponse` - Response data

### `get`

Get webhook
Get a list of webhook configs associated with a client app.

#### Parameters

<ParamField type="List or None">
  A comma separated list of WebhookConfig fields to display.
</ParamField>

#### Returns

`GetResponse` - Response data

### `get_stream_links`

Get stream links
Get a list of webhook links associated with a filtered stream ruleset.
:returns: Response data
:rtype: GetStreamLinksResponse

#### Returns

`GetStreamLinksResponse`

### `validate`

Validate webhook
Triggers a CRC check for a given webhook.

#### Parameters

<ParamField type="Any">
  The ID of the webhook to check.
</ParamField>

#### Returns

`ValidateResponse` - Response data


# WebhooksClient
Source: https://docs.x.com/xdks/python/reference/xdk.webhooks.client

Reference for the webhooks.client Python module in the X API SDK. Client class and methods for calling the webhooks endpoints of the X API v2.

## WebhooksClient

<Badge>Class</Badge>

<Badge>Bases: object</Badge>

Client for webhooks operations

## Constructors

### `__init__`

#### Parameters

<ParamField type="Client" />

### `create`

Create webhook
Creates a new webhook configuration.
body: Request body
:returns: Response data
:rtype: CreateResponse

#### Parameters

<ParamField type="CreateRequest" />

### `create_stream_link`

Create stream link
Creates a link to deliver FilteredStream events to the given webhook.

#### Parameters

<ParamField type="Any">
  The webhook ID to link to your FilteredStream ruleset.
</ParamField>

<ParamField type="str or None">
  A comma separated list of Tweet fields to display.
</ParamField>

<ParamField type="str or None">
  A comma separated list of fields to expand.
</ParamField>

<ParamField type="str or None">
  A comma separated list of Media fields to display.
</ParamField>

<ParamField type="str or None">
  A comma separated list of Poll fields to display.
</ParamField>

<ParamField type="str or None">
  A comma separated list of User fields to display.
</ParamField>

<ParamField type="str or None">
  A comma separated list of Place fields to display.
</ParamField>

#### Returns

`CreateStreamLinkResponse` - Response data

### `create_webhook_replay_job`

Create replay job for webhook
Creates a replay job to retrieve events from up to the past 24 hours for all events delivered or attempted to be delivered to the webhook.
body: Request body
:returns: Response data
:rtype: CreateWebhookReplayJobResponse

#### Parameters

<ParamField type="CreateWebhookReplayJobRequest" />

### `delete`

Delete webhook
Deletes an existing webhook configuration.

#### Parameters

<ParamField type="Any">
  The ID of the webhook to delete.
</ParamField>

#### Returns

`DeleteResponse` - Response data

### `delete_stream_link`

Delete stream link
Deletes a link from FilteredStream events to the given webhook.

#### Parameters

<ParamField type="Any">
  The webhook ID to link to your FilteredStream ruleset.
</ParamField>

#### Returns

`DeleteStreamLinkResponse` - Response data

### `get`

Get webhook
Get a list of webhook configs associated with a client app.

#### Parameters

<ParamField type="List or None">
  A comma separated list of WebhookConfig fields to display.
</ParamField>

#### Returns

`GetResponse` - Response data

### `get_stream_links`

Get stream links
Get a list of webhook links associated with a filtered stream ruleset.
:returns: Response data
:rtype: GetStreamLinksResponse

#### Returns

`GetStreamLinksResponse`

### `validate`

Validate webhook
Triggers a CRC check for a given webhook.

#### Parameters

<ParamField type="Any">
  The ID of the webhook to check.
</ParamField>

#### Returns

`ValidateResponse` - Response data


# Webhooks.Models
Source: https://docs.x.com/xdks/python/reference/xdk.webhooks.models

Reference for the webhooks.models Python module in the X API SDK. Pydantic request and response models for the webhooks endpoints of the X API v2.

This module provides Pydantic models for request and response data structures
for the webhooks endpoints of the X API. All models are generated
from the OpenAPI specification and provide type safety and validation.

### class xdk.webhooks.models.CreateRequest

Request model for create

<ResponseField name="model_config" type="ConfigDict">
  Default: `{'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}`

  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
</ResponseField>

## CreateResponse

<Badge>Class</Badge>

<Badge>Bases: BaseModel</Badge>

Response model for create

## Methods

### `class xdk.webhooks.models.CreateResponse`

Response model for create

### `class xdk.webhooks.models.CreateStreamLinkResponse`

Response model for create\_stream\_link

### `class xdk.webhooks.models.CreateWebhookReplayJobResponse`

Response model for create\_webhook\_replay\_job

### `class xdk.webhooks.models.DeleteResponse`

Response model for delete

### `class xdk.webhooks.models.DeleteStreamLinkResponse`

Response model for delete\_stream\_link

### `class xdk.webhooks.models.GetResponse`

Response model for get

### `class xdk.webhooks.models.GetStreamLinksResponse`

Response model for get\_stream\_links

### `class xdk.webhooks.models.ValidateResponse`

Response model for validate


# Streaming
Source: https://docs.x.com/xdks/python/streaming

The X API supports real-time data via endpoints like the Filtered Stream Endpoint, delivering matching Posts as they occur. This requires making a persistent.

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

```python theme={null}
from xdk import Client
# Initialize client
client = Client(bearer_token="your_bearer_token")
# Stream posts (make sure you have rules set up first)
for post_response in client.stream.posts():
    data = post_response.model_dump() if hasattr(post_response, 'model_dump') else dict(post_response)
    if 'data' in data and data['data']:
        tweet = data['data']
        post_text = tweet.get('text', '') if isinstance(tweet, dict) else (tweet.text if hasattr(tweet, 'text') else '')
        print(f"Post: {post_text}")
```

### Async

```python title="Example" expandable lines wrap icon="python" theme={null}
import asyncio
from asyncio import Queue
import threading
from xdk import Client
async def stream_posts_async(client: Client):
    queue = Queue()
    loop = asyncio.get_event_loop()
    stop = threading.Event()
    def run_stream():
        for post in client.stream.posts():
            if stop.is_set():
                break
            asyncio.run_coroutine_threadsafe(queue.put(post), loop)
        asyncio.run_coroutine_threadsafe(queue.put(None), loop)
    threading.Thread(target=run_stream, daemon=True).start()
    while True:
        post = await queue.get()
        if post is None:
            break
        data = post.model_dump()
        if 'data' in data and data['data']:
            print(f"Post: {data['data'].get('text', '')}")
    stop.set()
async def main():
    client = Client(bearer_token="your_bearer_token")
    await stream_posts_async(client)
asyncio.run(main())
```

## Rule Management

Rules define filters on what specific data you are looking for(e.g. keywords, users etc). You can learn more about how to build rules using [this guide](https://docs.x.com/x-api/posts/filtered-stream/integrate/build-a-rule)
**Adding Rules**:

```python theme={null}
from xdk.stream.models import UpdateRulesRequest
# Add a rule
add_rules = {
    "add": [
        {"value": "from:xdevelopers", "tag": "official_updates"}
    ]
}
request_body = UpdateRulesRequest(**add_rules)
response = client.stream.update_rules(body=request_body)
```

**Deleting Rules**:

```python theme={null}
from xdk.stream.models import UpdateRulesRequest
delete_rules = {
    "delete": {
        "ids": ["rule_id_1", "rule_id_2"]
    }
}
request_body = UpdateRulesRequest(**delete_rules)
response = client.stream.update_rules(body=request_body)
```

**Listing Rules**:

```python theme={null}
# get_rules returns an Iterator, so iterate over it
for page in client.stream.get_rules():
    if page.data:
        for rule in page.data:
            # Access rule attributes - Pydantic models support both attribute and dict access
            rule_id = rule.id if hasattr(rule, 'id') else rule.get('id', '')
            rule_value = rule.value if hasattr(rule, 'value') else rule.get('value', '')
            rule_tag = rule.tag if hasattr(rule, 'tag') else rule.get('tag', '')
            print(f"ID: {rule_id}, Value: {rule_value}, Tag: {rule_tag}")
    break  # Remove break to get all pages
```

For full rule syntax, see [X Streaming Rules Docs](https://developer.x.com/en/docs/twitter-api/tweets/filtered-stream/integrate/build-a-rule).

## Troubleshooting

* **403 Forbidden**: Invalid auth or insufficient permissions.
* **420 Enhance Your Calm**: Rate limited; wait and retry.
* **No Data**: Check rules with `get_rules()`; ensure matching Posts exist.
  For detailed code examples using the Python XDK, check out our [code samples GitHub repo](https://github.com/xdevplatform/samples/tree/main/python).
  For more examples and API reference, see the inline docstrings (e.g., `help(client.tweets.search_recent)`) or the generated stubs in the source. Contribute feedback via the [GitHub repo](https://github.com/xdevplatform/xdk/tree/main/xdk/python).


# Authentication
Source: https://docs.x.com/xdks/typescript/authentication

The TypeScript SDK supports multiple authentication methods for different use cases. For read-only operations and public data access: For legacy applications.

The TypeScript SDK supports multiple authentication methods for different use cases.

## Bearer Token (App-Only Auth)

For read-only operations and public data access:

<CodeGroup>
  ```typescript title="quickstart.ts" lines wrap icon="square-js" theme={null} theme={null}
  import { 
    Client, 
    type ClientConfig,
    type Users
  } from '@xdevplatform/xdk';

  const config: ClientConfig = { bearerToken: 'your-bearer-token' };

  const client: Client = new Client(config);

  async function main(): Promise<void> {
    const userResponse: Users.GetByUsernameResponse = await client.users.getByUsername('XDevelopers');
    const username: string = userResponse.data?.username!;
    console.log(username);
  }

  main();
  ```

  ```javascript quickstart.js theme={null} theme={null}
  import { Client } from '@xdevplatform/xdk';

  const client = new Client({ bearerToken: 'your-bearer-token' });

  const userResponse = await client.users.getByUsername('XDevelopers');
  const username = userResponse.data.username;
  console.log(username);
  ```
</CodeGroup>

## OAuth 1.0a (User Context)

For legacy applications or specific use cases:

<CodeGroup>
  ```typescript title="oauth1.ts" expandable lines wrap icon="square-js" theme={null} theme={null}
  import { 
    Client, 
    OAuth1,
    type OAuth1Config,
    type ClientConfig,
    type Users
  } from '@xdevplatform/xdk';

  const oauth1Config: OAuth1Config = {
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
    accessToken: 'user-access-token',
    accessTokenSecret: 'user-access-token-secret'
  };

  const oauth1: OAuth1 = new OAuth1(oauth1Config);

  const config: ClientConfig = {
    oauth1: oauth1,
  };

  const client: Client = new Client(config);

  async function main(): Promise<void> {
    const response: Users.GetMeResponse = await client.users.getMe();

    const me = response.data;
    console.log(me);
  }

  main();

  ```

  ```javascript title="oauth1.js" lines wrap icon="square-js" theme={null} theme={null}
  import { Client, OAuth1 } from '@xdevplatform/xdk';

  const oauth1 = new OAuth1({
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
    accessToken: 'user-access-token',
    accessTokenSecret: 'user-access-token-secret'
  });

  const client = new Client({ oauth1: oauth1 });

  const response = await client.users.getMe();
  const me = response.data;
  console.log(me);

  ```
</CodeGroup>

## OAuth 2.0 (User Context)

For user-specific operations:

<CodeGroup>
  ```typescript title="oauth2.ts" expandable lines wrap icon="square-js" theme={null} theme={null}
  import { 
    Client, 
    OAuth2,
    generateCodeVerifier,
    generateCodeChallenge,
    type OAuth2Config,
    type ClientConfig,
    type OAuth2Token
  } from '@xdevplatform/xdk';

  (async (): Promise<void> => {
    const oauth2Config: OAuth2Config = {
      clientId: 'your-client-id',
      clientSecret: 'your-client-secret',
      redirectUri: 'https://example.com',
      scope: ['tweet.read', 'users.read', 'offline.access'],
    };

    const oauth2: OAuth2 = new OAuth2(oauth2Config);

    const state: string = 'example-state';
    const codeVerifier: string = generateCodeVerifier();
    const codeChallenge: string = await generateCodeChallenge(codeVerifier);
    
    oauth2.setPkceParameters(codeVerifier, codeChallenge);
    
    const authUrl: string = await oauth2.getAuthorizationUrl(state);

    // User visits authUrl and authorizes the app
    // After authorization, user is redirected back with a code parameter
    // Extract the code from the callback URL (e.g., from query params)
    const authCode: string = 'code-from-callback-url'; // Replace with actual code from OAuth callback

    const tokens: OAuth2Token = await oauth2.exchangeCode(authCode, codeVerifier);

    const config: ClientConfig = {
      accessToken: tokens.access_token,
    };

    const client: Client = new Client(config);
  });

  ```

  ```javascript title="oauth2.js" expandable lines wrap icon="square-js" theme={null} theme={null}
  import { Client, OAuth2, generateCodeVerifier, generateCodeChallenge } from '@xdevplatform/xdk';

  (async () => {
    const oauth2 = new OAuth2({
      clientId: 'your-client-id',
      clientSecret: 'your-client-secret',
      redirectUri: 'https://example.com',
      scope: ['tweet.read', 'users.read', 'offline.access'],
    });

    const state = 'example-state';
    const codeVerifier = generateCodeVerifier();
    const codeChallenge = await generateCodeChallenge(codeVerifier);
    oauth2.setPkceParameters(codeVerifier, codeChallenge);
    const authUrl = await oauth2.getAuthorizationUrl(state);

    // User visits authUrl and authorizes the app
    // After authorization, user is redirected back with a code parameter
    // Extract the code from the callback URL (e.g., from query params)
    const authCode = 'code-from-callback-url'; // Replace with actual code from OAuth callback

    const tokens = await oauth2.exchangeCode(authCode, codeVerifier);

    const client = new Client({ accessToken: tokens.access_token });

    const response = await client.users.getMe();
    const me = response.data;
    console.log(me);
  });
  ```
</CodeGroup>

## Environment Variables

Store sensitive credentials in environment variables:

```bash theme={null}
# .env
X_API_BEARER_TOKEN=your-bearer-token
X_API_CLIENT_ID=your-client-id
X_API_CLIENT_SECRET=your-client-secret
```

<CodeGroup>
  ```typescript env.ts theme={null} theme={null}
  import { Client } from '@xdevplatform/xdk';

  const client = new Client({ bearerToken: process.env.X_API_BEARER_TOKEN });
  ```

  ```javascript env.js theme={null} theme={null}
  import { Client } from '@xdevplatform/xdk';

  const client = new Client({ bearerToken: process.env.X_API_BEARER_TOKEN });
  ```
</CodeGroup>

<Info>
  For detailed code examples using the Javascript/TypeScript XDK, check out our [code samples GitHub repo](https://github.com/xdevplatform/samples/tree/main/javascript).
</Info>


# Installation
Source: https://docs.x.com/xdks/typescript/install

Get started with the TypeScript SDK for X API in your project. The SDK is written in TypeScript and includes full type definitions.

Get started with the TypeScript SDK for X API in your project.

## Install

<CodeGroup>
  ```bash npm theme={null} theme={null}
  npm install @xdevplatform/xdk
  ```

  ```bash yarn theme={null} theme={null}
  yarn add @xdevplatform/xdk
  ```

  ```bash pnpm theme={null} theme={null}
  pnpm add @xdevplatform/xdk
  ```
</CodeGroup>

## TypeScript Support

The SDK is written in TypeScript and includes full type definitions. No additional type packages are required.

## Requirements

* Node.js 16+
* TypeScript 4.5+ (if using TypeScript)

## Next Steps

* [Authentication](/xdks/typescript/authentication) - Set up authentication
* [Quick Start](/xdks/typescript/overview) - Your first API call

<Info>
  For detailed code examples using the Javascript/TypeScript XDK, check out our [code samples GitHub repo](https://github.com/xdevplatform/samples/tree/main/javascript).
</Info>


# TypeScript XDK
Source: https://docs.x.com/xdks/typescript/overview

Overview of the TypeScript XDK for the X API v2, with smart pagination, OAuth 1.0a, OAuth 2.0, bearer token auth, real-time streaming, and full type safety.

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.

## Key Features

* **🔐 Authentication**: User Context (OAuth1.0a, OAuth2.0), and App-Only (Bearer token) authentication
* **🔄 Pagination**: Automatic pagination with async iteration support
* **📡 Streaming**: Event-driven streaming with automatic reconnection
* **📚 Type Safety**: Complete TypeScript definitions for all endpoints and parameters
* **🎯 Full X API Support**: Users, Posts, Lists, Bookmarks, Communities, and more

## Quick Start

<CodeGroup>
  ```typescript title="quickstart.ts" lines wrap icon="square-js" theme={null} theme={null}
  import { 
      Client, 
      type ClientConfig,
      type Users
  } from '@xdevplatform/xdk';

  const config: ClientConfig = { bearerToken: 'your-bearer-token' };

  const client: Client = new Client(config);

  async function main(): Promise<void> {
    const userResponse: Users.GetByUsernameResponse = await client.users.getByUsername('XDevelopers');
    const username: string = userResponse.data?.username!;
    console.log(username);
  }

  main();
  ```

  ```javascript quickstart.js theme={null} theme={null}
  import { Client } from '@xdevplatform/xdk';

  const client = new Client({ bearerToken: 'your-bearer-token' });

  const userResponse = await client.users.getByUsername('XDevelopers');
  const username = userResponse.data.username;
  console.log(username);
  ```
</CodeGroup>

<Info>
  For detailed code examples using the Javascript/TypeScript XDK, check out our [code samples GitHub repo](https://github.com/xdevplatform/samples/tree/main/javascript).
</Info>

## What's Next?

* [Installation Guide](/xdks/typescript/install) - Set up the SDK in your project
* [Authentication](/xdks/typescript/authentication) - Learn about different auth methods
* [Pagination](/xdks/typescript/pagination) - Learn about data pagination
* [Streaming](/xdks/typescript/streaming) - Learn about real-time data streaming
* [API Reference](/xdks/typescript/reference/classes/Client) - Read the complete API documentation


# Pagination
Source: https://docs.x.com/xdks/typescript/pagination

Paginate X API responses in TypeScript using UserPaginator and generic paginator utilities with manual fetchNext loops or async iteration for any list endpoint.

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.

### Basic Pagination

<CodeGroup>
  ```typescript title="quick-start.ts" lines wrap icon="square-js" theme={null} theme={null}
  import { Client, UserPaginator, PaginatedResponse, Schemas } from '@xdevplatform/xdk';

  const client: Client = new Client({ bearerToken: 'your-bearer-token' });

  // Wrap any list endpoint with proper typing
  const followers: UserPaginator = new UserPaginator(
    async (token?: string): Promise<PaginatedResponse<Schemas.User>> => {
      const res = await client.users.getFollowers('<userId>', {
        maxResults: 100,
        paginationToken: token,
        userFields: ['id','name','username'],
      });
      return { 
        data: res.data ?? [], 
        meta: res.meta, 
        includes: res.includes, 
        errors: res.errors 
      };
    }
  );
  ```

  ```javascript title="quick-start.js" lines wrap icon="square-js" theme={null} theme={null}
  import { Client } from '@xdevplatform/xdk';
  import { UserPaginator } from '@xdevplatform/xdk';

  const client = new Client({ bearerToken: 'your-bearer-token' });

  const followers = new UserPaginator(async (token) => {
    const res = await client.users.getFollowers('<userId>', {
      maxResults: 100,
      paginationToken: token,
      userFields: ['id','name','username'],
    });
    return { data: res.data ?? [], meta: res.meta, includes: res.includes, errors: res.errors };
  });
  ```
</CodeGroup>

### Manual paging

<CodeGroup>
  ```typescript manual.ts theme={null} theme={null}
  import { UserPaginator, Schemas } from '@xdevplatform/xdk';

  await followers.fetchNext();          // first page
  while (!followers.done) {
    await followers.fetchNext();        // subsequent pages
  }

  const userCount: number = followers.users.length;  // all fetched users
  const firstUser: Schemas.User | undefined = followers.users[0];
  const nextToken: string | undefined = followers.meta?.nextToken;
  ```

  ```javascript manual.js theme={null} theme={null}
  await followers.fetchNext();
  while (!followers.done) await followers.fetchNext();
  console.log(followers.items.length);
  ```
</CodeGroup>

### Async iteration

<CodeGroup>
  ```typescript async.ts theme={null} theme={null}
  import { Schemas } from '@xdevplatform/xdk';

  for await (const user of followers) {
    const typedUser: Schemas.User = user;
    console.log(typedUser.username);  // fully typed access
  }
  ```

  ```javascript async.js theme={null} theme={null}
  for await (const user of followers) {
    console.log(user.username);
  }
  ```
</CodeGroup>

### Next page as a new instance

<CodeGroup>
  ```typescript next.ts theme={null} theme={null}
  import { UserPaginator } from '@xdevplatform/xdk';

  await followers.fetchNext();
  if (!followers.done) {
    const page2: UserPaginator = await followers.next(); // independent paginator starting at next page
    await page2.fetchNext();
    console.log(page2.users.length);  // items from second page
  }
  ```

  ```javascript next.js theme={null} theme={null}
  await followers.fetchNext();
  if (!followers.done) {
    const page2 = await followers.next();
    await page2.fetchNext();
  }
  ```
</CodeGroup>

### Error handling and rate limits

<CodeGroup>
  ```typescript title="errors.ts" lines wrap icon="square-js" theme={null} theme={null}
  import { UserPaginator, Schemas } from '@xdevplatform/xdk';

  try {
    for await (const item of followers) {
      const user: Schemas.User = item;
      // process user...
    }
  } catch (err: unknown) {
    if (followers.rateLimited) {
      console.error('Rate limited, backoff required');
      // backoff / retry later
    } else {
      console.error('Pagination error:', err);
      throw err;
    }
  }
  ```

  ```javascript errors.js theme={null} theme={null}
  try {
    for await (const item of followers) {
      // ...
    }
  } catch (err) {
    if (followers.rateLimited) {
      // backoff / retry later
    } else {
      throw err;
    }
  }
  ```
</CodeGroup>

<Info>
  For detailed code examples using the Javascript/TypeScript XDK, check out our [code samples GitHub repo](https://github.com/xdevplatform/samples/tree/main/javascript).
</Info>


# AccountActivityClient
Source: https://docs.x.com/xdks/typescript/reference/classes/AccountActivityClient

Reference for the AccountActivityClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 account activity endpoints.

Client for account activity operations

This client provides methods for interacting with the account activity endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all account activity related operations.

## Constructors

### constructor

• **new AccountActivityClient**(`client`): [`AccountActivityClient`](/xdks/typescript/reference/classes/AccountActivityClient)

Creates a new account activity client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`AccountActivityClient`](/xdks/typescript/reference/classes/AccountActivityClient)

#### Defined in

[account\_activity/client.ts:70](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L70)

## Methods

### getSubscriptions

▸ **getSubscriptions**(`webhookId`, `options`): `Promise`\<`Response`>

Get subscriptions
Retrieves a list of all active subscriptions for a given webhook.

#### Parameters

| Name                         | Type     | Description                               |
| :--------------------------- | :------- | :---------------------------------------- |
| `webhookId`                  | `string` | The webhook ID to pull subscriptions for. |
| `options`                    | `Object` | -                                         |
| `options.requestOptions`     | `Object` | -                                         |
| `options.requestOptions.raw` | `true`   | -                                         |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[account\_activity/client.ts:115](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L115)

▸ **getSubscriptions**(`webhookId`): `Promise`\<[`SubscriptionsListGetResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsListGetResponse)>

#### Parameters

| Name        | Type     |
| :---------- | :------- |
| `webhookId` | `string` |

#### Returns

`Promise`\<[`SubscriptionsListGetResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsListGetResponse)>

#### Defined in

[account\_activity/client.ts:128](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L128)

***

### deleteSubscription

▸ **deleteSubscription**(`webhookId`, `userId`, `options`): `Promise`\<`Response`>

Delete subscription
Deletes an Account Activity subscription for the given webhook and user ID.

#### Parameters

| Name                         | Type     | Description                                   |
| :--------------------------- | :------- | :-------------------------------------------- |
| `webhookId`                  | `string` | The webhook ID to check subscription against. |
| `userId`                     | `string` | User ID to unsubscribe from.                  |
| `options`                    | `Object` | -                                             |
| `options.requestOptions`     | `Object` | -                                             |
| `options.requestOptions.raw` | `true`   | -                                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[account\_activity/client.ts:217](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L217)

▸ **deleteSubscription**(`webhookId`, `userId`): `Promise`\<[`SubscriptionsDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsDeleteResponse)>

#### Parameters

| Name        | Type     |
| :---------- | :------- |
| `webhookId` | `string` |
| `userId`    | `string` |

#### Returns

`Promise`\<[`SubscriptionsDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsDeleteResponse)>

#### Defined in

[account\_activity/client.ts:234](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L234)

***

### validateSubscription

▸ **validateSubscription**(`webhookId`, `options`): `Promise`\<`Response`>

Validate subscription
Checks a user’s Account Activity subscription for a given webhook.

#### Parameters

| Name                         | Type     | Description                                   |
| :--------------------------- | :------- | :-------------------------------------------- |
| `webhookId`                  | `string` | The webhook ID to check subscription against. |
| `options`                    | `Object` | -                                             |
| `options.requestOptions`     | `Object` | -                                             |
| `options.requestOptions.raw` | `true`   | -                                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[account\_activity/client.ts:331](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L331)

▸ **validateSubscription**(`webhookId`): `Promise`\<[`SubscriptionsGetResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsGetResponse)>

#### Parameters

| Name        | Type     |
| :---------- | :------- |
| `webhookId` | `string` |

#### Returns

`Promise`\<[`SubscriptionsGetResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsGetResponse)>

#### Defined in

[account\_activity/client.ts:344](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L344)

***

### createSubscription

▸ **createSubscription**(`webhookId`, `options`): `Promise`\<`Response`>

Create subscription
Creates an Account Activity subscription for the user and the given webhook.

#### Parameters

| Name        | Type                                                                      | Description                                   |
| :---------- | :------------------------------------------------------------------------ | :-------------------------------------------- |
| `webhookId` | `string`                                                                  | The webhook ID to check subscription against. |
| `options`   | `CreateSubscriptionOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[account\_activity/client.ts:435](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L435)

▸ **createSubscription**(`webhookId`, `options?`): `Promise`\<[`SubscriptionsCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsCreateResponse)>

#### Parameters

| Name        | Type                        |
| :---------- | :-------------------------- |
| `webhookId` | `string`                    |
| `options?`  | `CreateSubscriptionOptions` |

#### Returns

`Promise`\<[`SubscriptionsCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsCreateResponse)>

#### Defined in

[account\_activity/client.ts:448](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L448)

***

### createReplayJob

▸ **createReplayJob**(`webhookId`, `fromDate`, `toDate`, `options`): `Promise`\<`Response`>

Create replay job
Creates a replay job to retrieve activities from up to the past 5 days for all subscriptions associated with a given webhook.

#### Parameters

| Name                         | Type     | Description                                                                                                   |
| :--------------------------- | :------- | :------------------------------------------------------------------------------------------------------------ |
| `webhookId`                  | `string` | The unique identifier for the webhook configuration.                                                          |
| `fromDate`                   | `string` | The oldest (starting) UTC timestamp (inclusive) from which events will be provided, in `yyyymmddhhmm` format. |
| `toDate`                     | `string` | The latest (ending) UTC timestamp (exclusive) up to which events will be provided, in `yyyymmddhhmm` format.  |
| `options`                    | `Object` | -                                                                                                             |
| `options.requestOptions`     | `Object` | -                                                                                                             |
| `options.requestOptions.raw` | `true`   | -                                                                                                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[account\_activity/client.ts:564](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L564)

▸ **createReplayJob**(`webhookId`, `fromDate`, `toDate`): `Promise`\<[`ReplayJobCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.ReplayJobCreateResponse)>

#### Parameters

| Name        | Type     |
| :---------- | :------- |
| `webhookId` | `string` |
| `fromDate`  | `string` |
| `toDate`    | `string` |

#### Returns

`Promise`\<[`ReplayJobCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.ReplayJobCreateResponse)>

#### Defined in

[account\_activity/client.ts:585](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L585)

***

### getSubscriptionCount

▸ **getSubscriptionCount**(`options`): `Promise`\<`Response`>

Get subscription count
Retrieves a count of currently active Account Activity subscriptions.

#### Parameters

| Name                         | Type     |
| :--------------------------- | :------- |
| `options`                    | `Object` |
| `options.requestOptions`     | `Object` |
| `options.requestOptions.raw` | `true`   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[account\_activity/client.ts:704](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L704)

▸ **getSubscriptionCount**(): `Promise`\<[`SubscriptionsCountGetResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsCountGetResponse)>

#### Returns

`Promise`\<[`SubscriptionsCountGetResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsCountGetResponse)>

#### Defined in

[account\_activity/client.ts:713](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/client.ts#L713)


# ActivityClient
Source: https://docs.x.com/xdks/typescript/reference/classes/ActivityClient

Reference for the ActivityClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 activity endpoints.

Client for activity operations

This client provides methods for interacting with the activity endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all activity related operations.

## Constructors

### constructor

• **new ActivityClient**(`client`): [`ActivityClient`](/xdks/typescript/reference/classes/ActivityClient)

Creates a new activity client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`ActivityClient`](/xdks/typescript/reference/classes/ActivityClient)

#### Defined in

[activity/client.ts:118](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/client.ts#L118)

## Methods

### getSubscriptions

▸ **getSubscriptions**(`options`): `Promise`\<`Response`>

Get X activity subscriptions
Get a list of active subscriptions for XAA

#### Parameters

| Name                         | Type     |
| :--------------------------- | :------- |
| `options`                    | `Object` |
| `options.requestOptions`     | `Object` |
| `options.requestOptions.raw` | `true`   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[activity/client.ts:159](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/client.ts#L159)

▸ **getSubscriptions**(): `Promise`\<[`ActivitySubscriptionGetResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionGetResponse)>

#### Returns

`Promise`\<[`ActivitySubscriptionGetResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionGetResponse)>

#### Defined in

[activity/client.ts:168](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/client.ts#L168)

***

### createSubscription

▸ **createSubscription**(`options`): `Promise`\<`Response`>

Create X activity subscription
Creates a subscription for an X activity event

#### Parameters

| Name      | Type                                                                      |
| :-------- | :------------------------------------------------------------------------ |
| `options` | `CreateSubscriptionOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[activity/client.ts:237](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/client.ts#L237)

▸ **createSubscription**(`options?`): `Promise`\<[`ActivitySubscriptionCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateResponse)>

#### Parameters

| Name       | Type                        |
| :--------- | :-------------------------- |
| `options?` | `CreateSubscriptionOptions` |

#### Returns

`Promise`\<[`ActivitySubscriptionCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateResponse)>

#### Defined in

[activity/client.ts:246](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/client.ts#L246)

***

### stream

▸ **stream**(`options`): `Promise`\<`Response`>

Activity Stream
Stream of X Activities

#### Parameters

| Name      | Type                                                          |
| :-------- | :------------------------------------------------------------ |
| `options` | `StreamOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[activity/client.ts:332](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/client.ts#L332)

▸ **stream**(`options?`): `Promise`\<[`ActivityStreamingResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivityStreamingResponse)>

#### Parameters

| Name       | Type            |
| :--------- | :-------------- |
| `options?` | `StreamOptions` |

#### Returns

`Promise`\<[`ActivityStreamingResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivityStreamingResponse)>

#### Defined in

[activity/client.ts:341](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/client.ts#L341)

***

### updateSubscription

▸ **updateSubscription**(`subscriptionId`, `options`): `Promise`\<`Response`>

Update X activity subscription
Updates a subscription for an X activity event

#### Parameters

| Name             | Type                                                                      | Description                           |
| :--------------- | :------------------------------------------------------------------------ | :------------------------------------ |
| `subscriptionId` | `string`                                                                  | The ID of the subscription to update. |
| `options`        | `UpdateSubscriptionOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                     |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[activity/client.ts:487](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/client.ts#L487)

▸ **updateSubscription**(`subscriptionId`, `options?`): `Promise`\<[`ActivitySubscriptionUpdateResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateResponse)>

#### Parameters

| Name             | Type                        |
| :--------------- | :-------------------------- |
| `subscriptionId` | `string`                    |
| `options?`       | `UpdateSubscriptionOptions` |

#### Returns

`Promise`\<[`ActivitySubscriptionUpdateResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateResponse)>

#### Defined in

[activity/client.ts:500](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/client.ts#L500)

***

### deleteSubscription

▸ **deleteSubscription**(`subscriptionId`, `options`): `Promise`\<`Response`>

Deletes X activity subscription
Deletes a subscription for an X activity event

#### Parameters

| Name                         | Type     | Description                           |
| :--------------------------- | :------- | :------------------------------------ |
| `subscriptionId`             | `string` | The ID of the subscription to delete. |
| `options`                    | `Object` | -                                     |
| `options.requestOptions`     | `Object` | -                                     |
| `options.requestOptions.raw` | `true`   | -                                     |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[activity/client.ts:602](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/client.ts#L602)

▸ **deleteSubscription**(`subscriptionId`): `Promise`\<[`ActivitySubscriptionDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionDeleteResponse)>

#### Parameters

| Name             | Type     |
| :--------------- | :------- |
| `subscriptionId` | `string` |

#### Returns

`Promise`\<[`ActivitySubscriptionDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionDeleteResponse)>

#### Defined in

[activity/client.ts:615](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/client.ts#L615)


# ApiError
Source: https://docs.x.com/xdks/typescript/reference/classes/ApiError

Reference for the ApiError class in the X API TypeScript SDK. Properties and methods for inspecting HTTP status, error codes, and X API error responses.

API Error class for handling X API errors

## Hierarchy

* `Error`

  ↳ **`ApiError`**

## Constructors

### constructor

• **new ApiError**(`message`, `status`, `statusText`, `headers`, `data?`): [`ApiError`](/xdks/typescript/reference/classes/ApiError)

#### Parameters

| Name         | Type      |
| :----------- | :-------- |
| `message`    | `string`  |
| `status`     | `number`  |
| `statusText` | `string`  |
| `headers`    | `Headers` |
| `data?`      | `any`     |

#### Returns

[`ApiError`](/xdks/typescript/reference/classes/ApiError)

#### Overrides

Error.constructor

[client.ts:123](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/client.ts#L123)

## Properties

<ResponseField name="status" type="number" />

<ResponseField name="statusText" type="string" />

<ResponseField name="headers" type="Headers" />

<ResponseField name="data" type="any" />


# Client
Source: https://docs.x.com/xdks/typescript/reference/classes/Client

Reference for the main Client class in the X API TypeScript SDK, the entry point exposing specialized clients for every X API v2 endpoint group.

Main client class for the X API

This is the primary entry point for interacting with the X API. It provides
access to all API endpoints through specialized client modules and handles
authentication, request configuration, and error handling.

**`Example`**

```typescript title="Example" lines wrap icon="square-js" theme={null}
import { Client } from '@xdevplatform/xdk';

const client = new Client({
  bearerToken: 'your-bearer-token'
});

// Get user information
const user = await client.users.getUser('783214');

// Get followers with pagination
const followers = await client.users.getFollowers('783214', {
  maxResults: 10,
  userFields: ['id', 'name', 'username']
});

// Iterate through followers
for await (const follower of followers) {
  console.log(follower.username);
}
```

## Constructors

### constructor

• **new Client**(`config`): [`Client`](/xdks/typescript/reference/classes/Client)

Creates a new X API client instance

#### Parameters

| Name     | Type  | Description                          |
| :------- | :---- | :----------------------------------- |
| `config` | `any` | Configuration options for the client |

#### Returns

[`Client`](/xdks/typescript/reference/classes/Client)

**`Example`**

```typescript title="Example" lines wrap icon="square-js" theme={null}
// Bearer token authentication
const client = new Client({
  bearerToken: 'your-bearer-token'
});

// OAuth2 authentication
const client = new Client({
  accessToken: 'your-access-token'
});

// OAuth1 authentication
const client = new Client({
  oauth1: oauth1Instance
});
```

[client.ts:401](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/client.ts#L401)

## Properties

<ResponseField name="baseUrl" type="string">
  Base URL for API requests
</ResponseField>

<ResponseField name="bearerToken" type="string">
  Bearer token for authentication
</ResponseField>

<ResponseField name="accessToken" type="string">
  OAuth2 access token
</ResponseField>

<ResponseField name="oauth1" type="any">
  OAuth1 instance for authentication
</ResponseField>

<ResponseField name="headers" type="Headers">
  Headers for requests
</ResponseField>

<ResponseField name="timeout" type="number">
  Request timeout in milliseconds
</ResponseField>

<ResponseField name="retry" type="boolean">
  Whether to automatically retry failed requests
</ResponseField>

<ResponseField name="maxRetries" type="number">
  Maximum number of retry attempts
</ResponseField>

<ResponseField name="httpClient" type="HttpClient = httpClient">
  HTTP client for making requests
</ResponseField>

<ResponseField name="general" type="GeneralClient">
  general client
</ResponseField>

<ResponseField name="accountActivity" type="AccountActivityClient">
  account activity client
</ResponseField>

<ResponseField name="communityNotes" type="CommunityNotesClient">
  community notes client
</ResponseField>

<ResponseField name="compliance" type="ComplianceClient">
  compliance client
</ResponseField>

<ResponseField name="connections" type="ConnectionsClient">
  connections client
</ResponseField>

<ResponseField name="users" type="UsersClient">
  users client
</ResponseField>

<ResponseField name="news" type="NewsClient">
  news client
</ResponseField>

<ResponseField name="spaces" type="SpacesClient">
  spaces client
</ResponseField>

<ResponseField name="activity" type="ActivityClient">
  activity client
</ResponseField>

<ResponseField name="usage" type="UsageClient">
  usage client
</ResponseField>

<ResponseField name="trends" type="TrendsClient">
  trends client
</ResponseField>

<ResponseField name="posts" type="PostsClient">
  posts client
</ResponseField>

<ResponseField name="directMessages" type="DirectMessagesClient">
  direct messages client
</ResponseField>

<ResponseField name="communities" type="CommunitiesClient">
  communities client
</ResponseField>

<ResponseField name="media" type="MediaClient">
  media client
</ResponseField>

<ResponseField name="webhooks" type="WebhooksClient">
  webhooks client
</ResponseField>

<ResponseField name="stream" type="StreamClient">
  stream client
</ResponseField>

<ResponseField name="lists" type="ListsClient">
  lists client
</ResponseField>

<ResponseField name="request" type="Promise<T>">
  Make an authenticated request to the X API

  This method handles authentication, request formatting, and error handling
  for all API requests. It automatically adds the appropriate authentication
  headers based on the client configuration.
</ResponseField>

<ResponseField name="isTokenExpired" type="boolean">
  Check if the OAuth2 token is expired
</ResponseField>

<ResponseField name="refreshToken" type="Promise<void>">
  Refresh the OAuth2 token
</ResponseField>

<ResponseField name="isAuthenticated" type="boolean">
  Get the current authentication status
</ResponseField>

<ResponseField name="mapSecuritySchemeToAuthTypes" type="string[]">
  Map OpenAPI security scheme names to internal authentication types
</ResponseField>

<ResponseField name="validateAuthentication" type="void">
  Validate that the required authentication method is available
</ResponseField>

<ResponseField name="getAvailableAuthTypes" type="string[]">
  Get available authentication types
</ResponseField>


# CommunitiesClient
Source: https://docs.x.com/xdks/typescript/reference/classes/CommunitiesClient

Reference for the CommunitiesClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 communities endpoints.

Client for communities operations

This client provides methods for interacting with the communities endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all communities related operations.

## Constructors

### constructor

• **new CommunitiesClient**(`client`): [`CommunitiesClient`](/xdks/typescript/reference/classes/CommunitiesClient)

Creates a new communities client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`CommunitiesClient`](/xdks/typescript/reference/classes/CommunitiesClient)

#### Defined in

[communities/client.ts:102](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/communities/client.ts#L102)

## Methods

### search

▸ **search**(`query`, `options`): `Promise`\<`Response`>

Search Communities
Retrieves a list of Communities matching the specified search query.

#### Parameters

| Name      | Type                                                          | Description                  |
| :-------- | :------------------------------------------------------------ | :--------------------------- |
| `query`   | `string`                                                      | Query to search communities. |
| `options` | `SearchOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                            |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[communities/client.ts:147](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/communities/client.ts#L147)

▸ **search**(`query`, `options?`): `Promise`\<[`Get2CommunitiesSearchResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesSearchResponse)>

#### Parameters

| Name       | Type            |
| :--------- | :-------------- |
| `query`    | `string`        |
| `options?` | `SearchOptions` |

#### Returns

`Promise`\<[`Get2CommunitiesSearchResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesSearchResponse)>

#### Defined in

[communities/client.ts:160](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/communities/client.ts#L160)

***

### getById

▸ **getById**(`id`, `options`): `Promise`\<`Response`>

Get Community by ID
Retrieves details of a specific Community by its ID.

#### Parameters

| Name      | Type                                                           | Description              |
| :-------- | :------------------------------------------------------------- | :----------------------- |
| `id`      | `string`                                                       | The ID of the Community. |
| `options` | `GetByIdOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                        |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[communities/client.ts:352](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/communities/client.ts#L352)

▸ **getById**(`id`, `options?`): `Promise`\<[`Get2CommunitiesIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesIdResponse)>

#### Parameters

| Name       | Type             |
| :--------- | :--------------- |
| `id`       | `string`         |
| `options?` | `GetByIdOptions` |

#### Returns

`Promise`\<[`Get2CommunitiesIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesIdResponse)>

#### Defined in

[communities/client.ts:365](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/communities/client.ts#L365)


# CommunityNotesClient
Source: https://docs.x.com/xdks/typescript/reference/classes/CommunityNotesClient

Reference for the CommunityNotesClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 community notes endpoints.

Client for community notes operations

This client provides methods for interacting with the community notes endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all community notes related operations.

## Constructors

### constructor

• **new CommunityNotesClient**(`client`): [`CommunityNotesClient`](/xdks/typescript/reference/classes/CommunityNotesClient)

Creates a new community notes client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`CommunityNotesClient`](/xdks/typescript/reference/classes/CommunityNotesClient)

#### Defined in

[community\_notes/client.ts:186](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/client.ts#L186)

## Methods

### searchEligiblePosts

▸ **searchEligiblePosts**(`testMode`, `options`): `Promise`\<`Response`>

Search for Posts Eligible for Community Notes
Returns all the posts that are eligible for community notes.

#### Parameters

| Name       | Type                                                                       | Description                                                                                                                                    |
| :--------- | :------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `testMode` | `boolean`                                                                  | If true, return a list of posts that are for the test. If false, return a list of posts that the bots can write proposed notes on the product. |
| `options`  | `SearchEligiblePostsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                                                                              |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[community\_notes/client.ts:231](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/client.ts#L231)

▸ **searchEligiblePosts**(`testMode`, `options?`): `Promise`\<[`Get2NotesSearchPostsEligibleForNotesResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchPostsEligibleForNotesResponse)>

#### Parameters

| Name       | Type                         |
| :--------- | :--------------------------- |
| `testMode` | `boolean`                    |
| `options?` | `SearchEligiblePostsOptions` |

#### Returns

`Promise`\<[`Get2NotesSearchPostsEligibleForNotesResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchPostsEligibleForNotesResponse)>

#### Defined in

[community\_notes/client.ts:244](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/client.ts#L244)

***

### evaluate

▸ **evaluate**(`options`): `Promise`\<`Response`>

Evaluate a Community Note
Endpoint to evaluate a community note.

#### Parameters

| Name      | Type                                                            |
| :-------- | :-------------------------------------------------------------- |
| `options` | `EvaluateOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[community\_notes/client.ts:535](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/client.ts#L535)

▸ **evaluate**(`options?`): `Promise`\<[`EvaluateNoteResponse`](/xdks/typescript/reference/interfaces/Schemas.EvaluateNoteResponse)>

#### Parameters

| Name       | Type              |
| :--------- | :---------------- |
| `options?` | `EvaluateOptions` |

#### Returns

`Promise`\<[`EvaluateNoteResponse`](/xdks/typescript/reference/interfaces/Schemas.EvaluateNoteResponse)>

#### Defined in

[community\_notes/client.ts:544](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/client.ts#L544)

***

### searchWritten

▸ **searchWritten**(`testMode`, `options`): `Promise`\<`Response`>

Search for Community Notes Written
Returns all the community notes written by the user.

#### Parameters

| Name       | Type                                                                 | Description                                                                                                          |
| :--------- | :------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| `testMode` | `boolean`                                                            | If true, return the notes the caller wrote for the test. If false, return the notes the caller wrote on the product. |
| `options`  | `SearchWrittenOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                                                    |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[community\_notes/client.ts:640](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/client.ts#L640)

▸ **searchWritten**(`testMode`, `options?`): `Promise`\<[`Get2NotesSearchNotesWrittenResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchNotesWrittenResponse)>

#### Parameters

| Name       | Type                   |
| :--------- | :--------------------- |
| `testMode` | `boolean`              |
| `options?` | `SearchWrittenOptions` |

#### Returns

`Promise`\<[`Get2NotesSearchNotesWrittenResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchNotesWrittenResponse)>

#### Defined in

[community\_notes/client.ts:653](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/client.ts#L653)

***

### delete

▸ **delete**(`id`, `options`): `Promise`\<`Response`>

Delete a Community Note
Deletes a community note.

#### Parameters

| Name                         | Type     | Description                      |
| :--------------------------- | :------- | :------------------------------- |
| `id`                         | `string` | The community note id to delete. |
| `options`                    | `Object` | -                                |
| `options.requestOptions`     | `Object` | -                                |
| `options.requestOptions.raw` | `true`   | -                                |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[community\_notes/client.ts:826](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/client.ts#L826)

▸ **delete**(`id`): `Promise`\<[`DeleteNoteResponse`](/xdks/typescript/reference/interfaces/Schemas.DeleteNoteResponse)>

#### Parameters

| Name | Type     |
| :--- | :------- |
| `id` | `string` |

#### Returns

`Promise`\<[`DeleteNoteResponse`](/xdks/typescript/reference/interfaces/Schemas.DeleteNoteResponse)>

#### Defined in

[community\_notes/client.ts:839](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/client.ts#L839)

***

### create

▸ **create**(`options`): `Promise`\<`Response`>

Create a Community Note
Creates a community note endpoint for LLM use case.

#### Parameters

| Name      | Type                                                          |
| :-------- | :------------------------------------------------------------ |
| `options` | `CreateOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[community\_notes/client.ts:926](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/client.ts#L926)

▸ **create**(`options?`): `Promise`\<[`CreateNoteResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateNoteResponse)>

#### Parameters

| Name       | Type            |
| :--------- | :-------------- |
| `options?` | `CreateOptions` |

#### Returns

`Promise`\<[`CreateNoteResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateNoteResponse)>

#### Defined in

[community\_notes/client.ts:935](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/client.ts#L935)


# ComplianceClient
Source: https://docs.x.com/xdks/typescript/reference/classes/ComplianceClient

Reference for the ComplianceClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 compliance endpoints.

Client for compliance operations

This client provides methods for interacting with the compliance endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all compliance related operations.

## Constructors

### constructor

• **new ComplianceClient**(`client`): [`ComplianceClient`](/xdks/typescript/reference/classes/ComplianceClient)

Creates a new compliance client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`ComplianceClient`](/xdks/typescript/reference/classes/ComplianceClient)

#### Defined in

[compliance/client.ts:93](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/compliance/client.ts#L93)

## Methods

### getJobsById

▸ **getJobsById**(`id`, `options`): `Promise`\<`Response`>

Get Compliance Job by ID
Retrieves details of a specific Compliance Job by its ID.

#### Parameters

| Name      | Type                                                               | Description                               |
| :-------- | :----------------------------------------------------------------- | :---------------------------------------- |
| `id`      | `string`                                                           | The ID of the Compliance Job to retrieve. |
| `options` | `GetJobsByIdOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                         |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[compliance/client.ts:138](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/compliance/client.ts#L138)

▸ **getJobsById**(`id`, `options?`): `Promise`\<[`Get2ComplianceJobsIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsIdResponse)>

#### Parameters

| Name       | Type                 |
| :--------- | :------------------- |
| `id`       | `string`             |
| `options?` | `GetJobsByIdOptions` |

#### Returns

`Promise`\<[`Get2ComplianceJobsIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsIdResponse)>

#### Defined in

[compliance/client.ts:151](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/compliance/client.ts#L151)

***

### getJobs

▸ **getJobs**(`type`, `options`): `Promise`\<`Response`>

Get Compliance Jobs
Retrieves a list of Compliance Jobs filtered by job type and optional status.

#### Parameters

| Name      | Type                                                           | Description                     |
| :-------- | :------------------------------------------------------------- | :------------------------------ |
| `type`    | `string`                                                       | Type of Compliance Job to list. |
| `options` | `GetJobsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                               |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[compliance/client.ts:273](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/compliance/client.ts#L273)

▸ **getJobs**(`type`, `options?`): `Promise`\<[`Get2ComplianceJobsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsResponse)>

#### Parameters

| Name       | Type             |
| :--------- | :--------------- |
| `type`     | `string`         |
| `options?` | `GetJobsOptions` |

#### Returns

`Promise`\<[`Get2ComplianceJobsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsResponse)>

#### Defined in

[compliance/client.ts:286](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/compliance/client.ts#L286)

***

### createJobs

▸ **createJobs**(`body`, `options`): `Promise`\<`Response`>

Create Compliance Job
Creates a new Compliance Job for the specified job type.

#### Parameters

| Name                         | Type                                                                                                     | Description                                     |
| :--------------------------- | :------------------------------------------------------------------------------------------------------- | :---------------------------------------------- |
| `body`                       | [`CreateComplianceJobRequest`](/xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobRequest) | A request to create a new batch compliance job. |
| `options`                    | `Object`                                                                                                 | -                                               |
| `options.requestOptions`     | `Object`                                                                                                 | -                                               |
| `options.requestOptions.raw` | `true`                                                                                                   | -                                               |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[compliance/client.ts:430](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/compliance/client.ts#L430)

▸ **createJobs**(`body`): `Promise`\<[`CreateComplianceJobResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobResponse)>

#### Parameters

| Name   | Type                                                                                                     |
| :----- | :------------------------------------------------------------------------------------------------------- |
| `body` | [`CreateComplianceJobRequest`](/xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobRequest) |

#### Returns

`Promise`\<[`CreateComplianceJobResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobResponse)>

#### Defined in

[compliance/client.ts:441](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/compliance/client.ts#L441)


# ConnectionsClient
Source: https://docs.x.com/xdks/typescript/reference/classes/ConnectionsClient

Reference for the ConnectionsClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 connections endpoints.

Client for connections operations

This client provides methods for interacting with the connections endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all connections related operations.

## Constructors

### constructor

• **new ConnectionsClient**(`client`): [`ConnectionsClient`](/xdks/typescript/reference/classes/ConnectionsClient)

Creates a new connections client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`ConnectionsClient`](/xdks/typescript/reference/classes/ConnectionsClient)

#### Defined in

[connections/client.ts:88](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/connections/client.ts#L88)

## Methods

### getConnectionHistory

▸ **getConnectionHistory**(`options`): `Promise`\<`Response`>

Get Connection History
Returns active and historical streaming connections with disconnect reasons for the authenticated application.

#### Parameters

| Name      | Type                                                                        |
| :-------- | :-------------------------------------------------------------------------- |
| `options` | `GetConnectionHistoryOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[connections/client.ts:129](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/connections/client.ts#L129)

▸ **getConnectionHistory**(`options?`): `Promise`\<[`Get2ConnectionsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ConnectionsResponse)>

#### Parameters

| Name       | Type                          |
| :--------- | :---------------------------- |
| `options?` | `GetConnectionHistoryOptions` |

#### Returns

`Promise`\<[`Get2ConnectionsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ConnectionsResponse)>

#### Defined in

[connections/client.ts:138](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/connections/client.ts#L138)

***

### deleteAll

▸ **deleteAll**(`options`): `Promise`\<`Response`>

Terminate all connections
Terminates all active streaming connections for the authenticated application.

#### Parameters

| Name                         | Type     |
| :--------------------------- | :------- |
| `options`                    | `Object` |
| `options.requestOptions`     | `Object` |
| `options.requestOptions.raw` | `true`   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[connections/client.ts:318](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/connections/client.ts#L318)

▸ **deleteAll**(): `Promise`\<[`KillAllConnectionsResponse`](/xdks/typescript/reference/interfaces/Schemas.KillAllConnectionsResponse)>

#### Returns

`Promise`\<[`KillAllConnectionsResponse`](/xdks/typescript/reference/interfaces/Schemas.KillAllConnectionsResponse)>

#### Defined in

[connections/client.ts:327](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/connections/client.ts#L327)


# DirectMessagesClient
Source: https://docs.x.com/xdks/typescript/reference/classes/DirectMessagesClient

Reference for the DirectMessagesClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 direct messages endpoints.

Client for direct messages operations

This client provides methods for interacting with the direct messages endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all direct messages related operations.

## Constructors

### constructor

• **new DirectMessagesClient**(`client`): [`DirectMessagesClient`](/xdks/typescript/reference/classes/DirectMessagesClient)

Creates a new direct messages client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`DirectMessagesClient`](/xdks/typescript/reference/classes/DirectMessagesClient)

#### Defined in

[direct\_messages/client.ts:340](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L340)

## Methods

### createByConversationId

▸ **createByConversationId**(`dmConversationId`, `options`): `Promise`\<`Response`>

Create DM message by conversation ID
Sends a new direct message to a specific conversation by its ID.

#### Parameters

| Name               | Type                                                                          | Description             |
| :----------------- | :---------------------------------------------------------------------------- | :---------------------- |
| `dmConversationId` | `string`                                                                      | The DM Conversation ID. |
| `options`          | `CreateByConversationIdOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                       |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[direct\_messages/client.ts:385](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L385)

▸ **createByConversationId**(`dmConversationId`, `options?`): `Promise`\<[`CreateDmEventResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse)>

#### Parameters

| Name               | Type                            |
| :----------------- | :------------------------------ |
| `dmConversationId` | `string`                        |
| `options?`         | `CreateByConversationIdOptions` |

#### Returns

`Promise`\<[`CreateDmEventResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse)>

#### Defined in

[direct\_messages/client.ts:398](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L398)

***

### getEventsByConversationId

▸ **getEventsByConversationId**(`id`, `options`): `Promise`\<`Response`>

Get DM events for a DM conversation
Retrieves direct message events for a specific conversation.

#### Parameters

| Name      | Type                                                                             | Description             |
| :-------- | :------------------------------------------------------------------------------- | :---------------------- |
| `id`      | `string`                                                                         | The DM conversation ID. |
| `options` | `GetEventsByConversationIdOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                       |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[direct\_messages/client.ts:506](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L506)

▸ **getEventsByConversationId**(`id`, `options?`): `Promise`\<[`Get2DmConversationsIdDmEventsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsIdDmEventsResponse)>

#### Parameters

| Name       | Type                               |
| :--------- | :--------------------------------- |
| `id`       | `string`                           |
| `options?` | `GetEventsByConversationIdOptions` |

#### Returns

`Promise`\<[`Get2DmConversationsIdDmEventsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsIdDmEventsResponse)>

#### Defined in

[direct\_messages/client.ts:519](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L519)

***

### createConversation

▸ **createConversation**(`options`): `Promise`\<`Response`>

Create DM conversation
Initiates a new direct message conversation with specified participants.

#### Parameters

| Name      | Type                                                                      |
| :-------- | :------------------------------------------------------------------------ |
| `options` | `CreateConversationOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[direct\_messages/client.ts:784](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L784)

▸ **createConversation**(`options?`): `Promise`\<[`CreateDmEventResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse)>

#### Parameters

| Name       | Type                        |
| :--------- | :-------------------------- |
| `options?` | `CreateConversationOptions` |

#### Returns

`Promise`\<[`CreateDmEventResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse)>

#### Defined in

[direct\_messages/client.ts:793](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L793)

***

### getEventsByParticipantId

▸ **getEventsByParticipantId**(`participantId`, `options`): `Promise`\<`Response`>

Get DM events for a DM conversation
Retrieves direct message events for a specific conversation.

#### Parameters

| Name            | Type                                                                            | Description                                                        |
| :-------------- | :------------------------------------------------------------------------------ | :----------------------------------------------------------------- |
| `participantId` | `string`                                                                        | The ID of the participant user for the One to One DM conversation. |
| `options`       | `GetEventsByParticipantIdOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                  |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[direct\_messages/client.ts:889](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L889)

▸ **getEventsByParticipantId**(`participantId`, `options?`): `Promise`\<[`Get2DmConversationsWithParticipantIdDmEventsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsWithParticipantIdDmEventsResponse)>

#### Parameters

| Name            | Type                              |
| :-------------- | :-------------------------------- |
| `participantId` | `string`                          |
| `options?`      | `GetEventsByParticipantIdOptions` |

#### Returns

`Promise`\<[`Get2DmConversationsWithParticipantIdDmEventsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsWithParticipantIdDmEventsResponse)>

#### Defined in

[direct\_messages/client.ts:902](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L902)

***

### getEvents

▸ **getEvents**(`options`): `Promise`\<`Response`>

Get DM events
Retrieves a list of recent direct message events across all conversations.

#### Parameters

| Name      | Type                                                             |
| :-------- | :--------------------------------------------------------------- |
| `options` | `GetEventsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[direct\_messages/client.ts:1167](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L1167)

▸ **getEvents**(`options?`): `Promise`\<[`Get2DmEventsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2DmEventsResponse)>

#### Parameters

| Name       | Type               |
| :--------- | :----------------- |
| `options?` | `GetEventsOptions` |

#### Returns

`Promise`\<[`Get2DmEventsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2DmEventsResponse)>

#### Defined in

[direct\_messages/client.ts:1176](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L1176)

***

### getEventsById

▸ **getEventsById**(`eventId`, `options`): `Promise`\<`Response`>

Get DM event by ID
Retrieves details of a specific direct message event by its ID.

#### Parameters

| Name      | Type                                                                 | Description  |
| :-------- | :------------------------------------------------------------------- | :----------- |
| `eventId` | `string`                                                             | dm event id. |
| `options` | `GetEventsByIdOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -            |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[direct\_messages/client.ts:1433](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L1433)

▸ **getEventsById**(`eventId`, `options?`): `Promise`\<[`Get2DmEventsEventIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2DmEventsEventIdResponse)>

#### Parameters

| Name       | Type                   |
| :--------- | :--------------------- |
| `eventId`  | `string`               |
| `options?` | `GetEventsByIdOptions` |

#### Returns

`Promise`\<[`Get2DmEventsEventIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2DmEventsEventIdResponse)>

#### Defined in

[direct\_messages/client.ts:1446](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L1446)

***

### deleteEvents

▸ **deleteEvents**(`eventId`, `options`): `Promise`\<`Response`>

Delete DM event
Deletes a specific direct message event by its ID, if owned by the authenticated user.

#### Parameters

| Name                         | Type     | Description                                   |
| :--------------------------- | :------- | :-------------------------------------------- |
| `eventId`                    | `string` | The ID of the direct-message event to delete. |
| `options`                    | `Object` | -                                             |
| `options.requestOptions`     | `Object` | -                                             |
| `options.requestOptions.raw` | `true`   | -                                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[direct\_messages/client.ts:1656](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L1656)

▸ **deleteEvents**(`eventId`): `Promise`\<[`DeleteDmResponse`](/xdks/typescript/reference/interfaces/Schemas.DeleteDmResponse)>

#### Parameters

| Name      | Type     |
| :-------- | :------- |
| `eventId` | `string` |

#### Returns

`Promise`\<[`DeleteDmResponse`](/xdks/typescript/reference/interfaces/Schemas.DeleteDmResponse)>

#### Defined in

[direct\_messages/client.ts:1669](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L1669)

***

### createByParticipantId

▸ **createByParticipantId**(`participantId`, `options`): `Promise`\<`Response`>

Create DM message by participant ID
Sends a new direct message to a specific participant by their ID.

#### Parameters

| Name            | Type                                                                         | Description                                            |
| :-------------- | :--------------------------------------------------------------------------- | :----------------------------------------------------- |
| `participantId` | `string`                                                                     | The ID of the recipient user that will receive the DM. |
| `options`       | `CreateByParticipantIdOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                      |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[direct\_messages/client.ts:1760](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L1760)

▸ **createByParticipantId**(`participantId`, `options?`): `Promise`\<[`CreateDmEventResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse)>

#### Parameters

| Name            | Type                           |
| :-------------- | :----------------------------- |
| `participantId` | `string`                       |
| `options?`      | `CreateByParticipantIdOptions` |

#### Returns

`Promise`\<[`CreateDmEventResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse)>

#### Defined in

[direct\_messages/client.ts:1773](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/client.ts#L1773)


# EventPaginator
Source: https://docs.x.com/xdks/typescript/reference/classes/EventPaginator

Reference for the EventPaginator class in the X API TypeScript SDK. Iterate paginated event results with async iterators and cursor helpers.

Paginator for events (like DM events)

## Hierarchy

* [`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>

  ↳ **`EventPaginator`**

## Constructors

### constructor

• **new EventPaginator**(`fetchPage`): [`EventPaginator`](/xdks/typescript/reference/classes/EventPaginator)

Creates a new paginator instance

#### Parameters

| Name        | Type                                                                                                                       | Description                                                   |
| :---------- | :------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
| `fetchPage` | (`token?`: `string`) => `Promise`\<[`PaginatedResponse`](/xdks/typescript/reference/interfaces/PaginatedResponse)\<`any`>> | Function that fetches a page of data given a pagination token |

#### Returns

[`EventPaginator`](/xdks/typescript/reference/classes/EventPaginator)

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[constructor](/xdks/typescript/reference/classes/Paginator#constructor)

#### Defined in

[paginator.ts:90](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L90)

## Accessors

### items

• `get` **items**(): `T`\[]

Get all fetched items

#### Returns

`T`\[]

#### Inherited from

Paginator.items

#### Defined in

[paginator.ts:97](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L97)

***

### meta

• `get` **meta**(): `any`

Get current pagination metadata

#### Returns

`any`

#### Inherited from

Paginator.meta

#### Defined in

[paginator.ts:104](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L104)

***

### includes

• `get` **includes**(): `undefined` | `Record`\<`string`, `any`>

Get current includes data

#### Returns

`undefined` | `Record`\<`string`, `any`>

#### Inherited from

Paginator.includes

#### Defined in

[paginator.ts:111](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L111)

***

### errors

• `get` **errors**(): `undefined` | `any`\[]

Get current errors

#### Returns

`undefined` | `any`\[]

#### Inherited from

Paginator.errors

#### Defined in

[paginator.ts:118](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L118)

***

### done

• `get` **done**(): `boolean`

Check if pagination is done

#### Returns

`boolean`

#### Inherited from

Paginator.done

#### Defined in

[paginator.ts:125](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L125)

***

### rateLimited

• `get` **rateLimited**(): `boolean`

Check if rate limit was hit

#### Returns

`boolean`

#### Inherited from

Paginator.rateLimited

#### Defined in

[paginator.ts:132](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L132)

***

### events

• `get` **events**(): `any`\[]

#### Returns

`any`\[]

#### Defined in

[paginator.ts:362](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L362)

## Methods

### fetchNext

▸ **fetchNext**(): `Promise`\<`void`>

Fetch the next page and add items to current instance

This method fetches the next page of data and appends the items to the
current paginator instance. It updates the pagination state and metadata.

#### Returns

`Promise`\<`void`>

**`Example`**

```typescript theme={null}
const followers = await client.users.getFollowers('783214');
await followers.fetchNext(); // Fetch first page
console.log(followers.items.length); // Number of followers

if (!followers.done) {
  await followers.fetchNext(); // Fetch second page
  console.log(followers.items.length); // Total followers across pages
}
```

**`Throws`**

When the API request fails

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[fetchNext](/xdks/typescript/reference/classes/Paginator#fetchnext)

#### Defined in

[paginator.ts:156](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L156)

***

### next

▸ **next**(): `Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>>

Get next page as a new instance

This method creates a new paginator instance that starts from the next page,
without affecting the current paginator's state.

#### Returns

`Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>>

New paginator instance for the next page

**`Example`**

```typescript theme={null}
const followers = await client.users.getFollowers('783214');
await followers.fetchNext(); // Fetch first page

if (!followers.done) {
  const nextPage = await followers.next(); // Get next page as new instance
  console.log(followers.items.length); // Still first page
  console.log(nextPage.items.length); // Second page
}
```

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[next](/xdks/typescript/reference/classes/Paginator#next)

#### Defined in

[paginator.ts:211](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L211)

***

### fetchPrevious

▸ **fetchPrevious**(): `Promise`\<`void`>

Fetch previous page (if supported)

#### Returns

`Promise`\<`void`>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[fetchPrevious](/xdks/typescript/reference/classes/Paginator#fetchprevious)

#### Defined in

[paginator.ts:225](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L225)

***

### previous

▸ **previous**(): `Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>>

Get previous page as a new instance

#### Returns

`Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[previous](/xdks/typescript/reference/classes/Paginator#previous)

#### Defined in

[paginator.ts:260](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L260)

***

### fetchLast

▸ **fetchLast**(`count`): `Promise`\<`void`>

Fetch up to a specified number of additional items

#### Parameters

| Name    | Type     |
| :------ | :------- |
| `count` | `number` |

#### Returns

`Promise`\<`void`>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[fetchLast](/xdks/typescript/reference/classes/Paginator#fetchlast)

#### Defined in

[paginator.ts:274](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L274)

***

### reset

▸ **reset**(): `void`

Reset paginator to initial state

#### Returns

`void`

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[reset](/xdks/typescript/reference/classes/Paginator#reset)

#### Defined in

[paginator.ts:288](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L288)

***

### \[iterator]

▸ **\[iterator]**(): `Iterator`\<`any`, `any`, `undefined`>

Iterator for all fetched items

#### Returns

`Iterator`\<`any`, `any`, `undefined`>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[\[iterator\]](/xdks/typescript/reference/classes/Paginator#iterator)

#### Defined in

[paginator.ts:303](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L303)

***

### \[asyncIterator]

▸ **\[asyncIterator]**(): `AsyncIterator`\<`any`, `any`, `undefined`>

Async iterator that fetches pages automatically

#### Returns

`AsyncIterator`\<`any`, `any`, `undefined`>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[\[asyncIterator\]](/xdks/typescript/reference/classes/Paginator#asynciterator)

#### Defined in

[paginator.ts:312](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L312)


# GeneralClient
Source: https://docs.x.com/xdks/typescript/reference/classes/GeneralClient

Reference for the GeneralClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 general endpoints.

Client for general operations

This client provides methods for interacting with the general endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all general related operations.

## Constructors

### constructor

• **new GeneralClient**(`client`): [`GeneralClient`](/xdks/typescript/reference/classes/GeneralClient)

Creates a new general client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`GeneralClient`](/xdks/typescript/reference/classes/GeneralClient)

#### Defined in

[general/client.ts:42](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/general/client.ts#L42)

## Methods

### getOpenApiSpec

▸ **getOpenApiSpec**(`options`): `Promise`\<`Response`>

Get OpenAPI Spec.
Retrieves the full OpenAPI Specification in JSON format. (See [https://github.com/OAI/OpenAPI-Specification/blob/master/README.md](https://github.com/OAI/OpenAPI-Specification/blob/master/README.md))

#### Parameters

| Name                         | Type     |
| :--------------------------- | :------- |
| `options`                    | `Object` |
| `options.requestOptions`     | `Object` |
| `options.requestOptions.raw` | `true`   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[general/client.ts:83](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/general/client.ts#L83)

▸ **getOpenApiSpec**(): `Promise`\<[`GetOpenApiSpecResponse`](/xdks/typescript/reference/modules/General#getopenapispecresponse)>

#### Returns

`Promise`\<[`GetOpenApiSpecResponse`](/xdks/typescript/reference/modules/General#getopenapispecresponse)>

#### Defined in

[general/client.ts:92](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/general/client.ts#L92)


# HttpClient
Source: https://docs.x.com/xdks/typescript/reference/classes/HttpClient

Reference for the HttpClient class in the X API TypeScript SDK. Universal HTTP client for Node.js and browsers used to send requests to the X API.

Universal HTTP client that works in both Node.js and browser environments

## Constructors

### constructor

• **new HttpClient**(): [`HttpClient`](/xdks/typescript/reference/classes/HttpClient)

#### Returns

[`HttpClient`](/xdks/typescript/reference/classes/HttpClient)

#### Defined in

[http-client.ts:43](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/http-client.ts#L43)

## Methods

### createHeaders

▸ **createHeaders**(`init?`): `Headers`

Create a new Headers instance

#### Parameters

| Name    | Type                                       |
| :------ | :----------------------------------------- |
| `init?` | `Record`\<`string`, `string`> \| `Headers` |

#### Returns

`Headers`

#### Defined in

[http-client.ts:99](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/http-client.ts#L99)

***

### request

▸ **request**(`url`, `options?`): `Promise`\<[`HttpResponse`](/xdks/typescript/reference/interfaces/HttpResponse)>

Make an HTTP request

#### Parameters

| Name      | Type                                                                                         |
| :-------- | :------------------------------------------------------------------------------------------- |
| `url`     | `string`                                                                                     |
| `options` | [`HttpClientRequestOptions`](/xdks/typescript/reference/interfaces/HttpClientRequestOptions) |

#### Returns

`Promise`\<[`HttpResponse`](/xdks/typescript/reference/interfaces/HttpResponse)>

#### Defined in

[http-client.ts:106](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/http-client.ts#L106)

***

### get

▸ **get**(`url`, `headers?`): `Promise`\<[`HttpResponse`](/xdks/typescript/reference/interfaces/HttpResponse)>

Make a GET request

#### Parameters

| Name       | Type                          |
| :--------- | :---------------------------- |
| `url`      | `string`                      |
| `headers?` | `Record`\<`string`, `string`> |

#### Returns

`Promise`\<[`HttpResponse`](/xdks/typescript/reference/interfaces/HttpResponse)>

#### Defined in

[http-client.ts:141](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/http-client.ts#L141)

***

### post

▸ **post**(`url`, `body?`, `headers?`): `Promise`\<[`HttpResponse`](/xdks/typescript/reference/interfaces/HttpResponse)>

Make a POST request

#### Parameters

| Name       | Type                          |
| :--------- | :---------------------------- |
| `url`      | `string`                      |
| `body?`    | `string`                      |
| `headers?` | `Record`\<`string`, `string`> |

#### Returns

`Promise`\<[`HttpResponse`](/xdks/typescript/reference/interfaces/HttpResponse)>

#### Defined in

[http-client.ts:151](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/http-client.ts#L151)

***

### put

▸ **put**(`url`, `body?`, `headers?`): `Promise`\<[`HttpResponse`](/xdks/typescript/reference/interfaces/HttpResponse)>

Make a PUT request

#### Parameters

| Name       | Type                          |
| :--------- | :---------------------------- |
| `url`      | `string`                      |
| `body?`    | `string`                      |
| `headers?` | `Record`\<`string`, `string`> |

#### Returns

`Promise`\<[`HttpResponse`](/xdks/typescript/reference/interfaces/HttpResponse)>

#### Defined in

[http-client.ts:162](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/http-client.ts#L162)

***

### delete

▸ **delete**(`url`, `headers?`): `Promise`\<[`HttpResponse`](/xdks/typescript/reference/interfaces/HttpResponse)>

Make a DELETE request

#### Parameters

| Name       | Type                          |
| :--------- | :---------------------------- |
| `url`      | `string`                      |
| `headers?` | `Record`\<`string`, `string`> |

#### Returns

`Promise`\<[`HttpResponse`](/xdks/typescript/reference/interfaces/HttpResponse)>

#### Defined in

[http-client.ts:173](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/http-client.ts#L173)

***

### patch

▸ **patch**(`url`, `body?`, `headers?`): `Promise`\<[`HttpResponse`](/xdks/typescript/reference/interfaces/HttpResponse)>

Make a PATCH request

#### Parameters

| Name       | Type                          |
| :--------- | :---------------------------- |
| `url`      | `string`                      |
| `body?`    | `string`                      |
| `headers?` | `Record`\<`string`, `string`> |

#### Returns

`Promise`\<[`HttpResponse`](/xdks/typescript/reference/interfaces/HttpResponse)>

#### Defined in

[http-client.ts:183](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/http-client.ts#L183)


# ListsClient
Source: https://docs.x.com/xdks/typescript/reference/classes/ListsClient

Reference for the ListsClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 lists endpoints.

Client for lists operations

This client provides methods for interacting with the lists endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all lists related operations.

## Constructors

### constructor

• **new ListsClient**(`client`): [`ListsClient`](/xdks/typescript/reference/classes/ListsClient)

Creates a new lists client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`ListsClient`](/xdks/typescript/reference/classes/ListsClient)

#### Defined in

[lists/client.ts:294](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L294)

## Methods

### getFollowers

▸ **getFollowers**(`id`, `options`): `Promise`\<`Response`>

Get List followers
Retrieves a list of Users who follow a specific List by its ID.

#### Parameters

| Name      | Type                                                                | Description         |
| :-------- | :------------------------------------------------------------------ | :------------------ |
| `id`      | `string`                                                            | The ID of the List. |
| `options` | `GetFollowersOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[lists/client.ts:339](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L339)

▸ **getFollowers**(`id`, `options?`): `Promise`\<[`Get2ListsIdFollowersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdFollowersResponse)>

#### Parameters

| Name       | Type                  |
| :--------- | :-------------------- |
| `id`       | `string`              |
| `options?` | `GetFollowersOptions` |

#### Returns

`Promise`\<[`Get2ListsIdFollowersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdFollowersResponse)>

#### Defined in

[lists/client.ts:352](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L352)

***

### create

▸ **create**(`options`): `Promise`\<`Response`>

Create List
Creates a new List for the authenticated user.

#### Parameters

| Name      | Type                                                          |
| :-------- | :------------------------------------------------------------ |
| `options` | `CreateOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[lists/client.ts:560](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L560)

▸ **create**(`options?`): `Promise`\<[`ListCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.ListCreateResponse)>

#### Parameters

| Name       | Type            |
| :--------- | :-------------- |
| `options?` | `CreateOptions` |

#### Returns

`Promise`\<[`ListCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.ListCreateResponse)>

#### Defined in

[lists/client.ts:569](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L569)

***

### getMembers

▸ **getMembers**(`id`, `options`): `Promise`\<`Response`>

Get List members
Retrieves a list of Users who are members of a specific List by its ID.

#### Parameters

| Name      | Type                                                              | Description         |
| :-------- | :---------------------------------------------------------------- | :------------------ |
| `id`      | `string`                                                          | The ID of the List. |
| `options` | `GetMembersOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[lists/client.ts:665](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L665)

▸ **getMembers**(`id`, `options?`): `Promise`\<[`Get2ListsIdMembersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdMembersResponse)>

#### Parameters

| Name       | Type                |
| :--------- | :------------------ |
| `id`       | `string`            |
| `options?` | `GetMembersOptions` |

#### Returns

`Promise`\<[`Get2ListsIdMembersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdMembersResponse)>

#### Defined in

[lists/client.ts:678](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L678)

***

### addMember

▸ **addMember**(`id`, `options`): `Promise`\<`Response`>

Add List member
Adds a User to a specific List by its ID.

#### Parameters

| Name      | Type                                                             | Description                                   |
| :-------- | :--------------------------------------------------------------- | :-------------------------------------------- |
| `id`      | `string`                                                         | The ID of the List for which to add a member. |
| `options` | `AddMemberOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[lists/client.ts:890](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L890)

▸ **addMember**(`id`, `options?`): `Promise`\<[`ListMutateResponse`](/xdks/typescript/reference/interfaces/Schemas.ListMutateResponse)>

#### Parameters

| Name       | Type               |
| :--------- | :----------------- |
| `id`       | `string`           |
| `options?` | `AddMemberOptions` |

#### Returns

`Promise`\<[`ListMutateResponse`](/xdks/typescript/reference/interfaces/Schemas.ListMutateResponse)>

#### Defined in

[lists/client.ts:903](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L903)

***

### getPosts

▸ **getPosts**(`id`, `options`): `Promise`\<`Response`>

Get List Posts
Retrieves a list of Posts associated with a specific List by its ID.

#### Parameters

| Name      | Type                                                            | Description         |
| :-------- | :-------------------------------------------------------------- | :------------------ |
| `id`      | `string`                                                        | The ID of the List. |
| `options` | `GetPostsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[lists/client.ts:1011](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L1011)

▸ **getPosts**(`id`, `options?`): `Promise`\<[`Get2ListsIdTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdTweetsResponse)>

#### Parameters

| Name       | Type              |
| :--------- | :---------------- |
| `id`       | `string`          |
| `options?` | `GetPostsOptions` |

#### Returns

`Promise`\<[`Get2ListsIdTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdTweetsResponse)>

#### Defined in

[lists/client.ts:1024](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L1024)

***

### removeMemberByUserId

▸ **removeMemberByUserId**(`id`, `userId`, `options`): `Promise`\<`Response`>

Remove List member
Removes a User from a specific List by its ID and the User’s ID.

#### Parameters

| Name                         | Type     | Description                                        |
| :--------------------------- | :------- | :------------------------------------------------- |
| `id`                         | `string` | The ID of the List to remove a member.             |
| `userId`                     | `string` | The ID of User that will be removed from the List. |
| `options`                    | `Object` | -                                                  |
| `options.requestOptions`     | `Object` | -                                                  |
| `options.requestOptions.raw` | `true`   | -                                                  |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[lists/client.ts:1303](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L1303)

▸ **removeMemberByUserId**(`id`, `userId`): `Promise`\<[`ListMutateResponse`](/xdks/typescript/reference/interfaces/Schemas.ListMutateResponse)>

#### Parameters

| Name     | Type     |
| :------- | :------- |
| `id`     | `string` |
| `userId` | `string` |

#### Returns

`Promise`\<[`ListMutateResponse`](/xdks/typescript/reference/interfaces/Schemas.ListMutateResponse)>

#### Defined in

[lists/client.ts:1320](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L1320)

***

### getById

▸ **getById**(`id`, `options`): `Promise`\<`Response`>

Get List by ID
Retrieves details of a specific List by its ID.

#### Parameters

| Name      | Type                                                           | Description         |
| :-------- | :------------------------------------------------------------- | :------------------ |
| `id`      | `string`                                                       | The ID of the List. |
| `options` | `GetByIdOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[lists/client.ts:1423](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L1423)

▸ **getById**(`id`, `options?`): `Promise`\<[`Get2ListsIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdResponse)>

#### Parameters

| Name       | Type             |
| :--------- | :--------------- |
| `id`       | `string`         |
| `options?` | `GetByIdOptions` |

#### Returns

`Promise`\<[`Get2ListsIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdResponse)>

#### Defined in

[lists/client.ts:1436](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L1436)

***

### update

▸ **update**(`id`, `options`): `Promise`\<`Response`>

Update List
Updates the details of a specific List owned by the authenticated user by its ID.

#### Parameters

| Name      | Type                                                          | Description                   |
| :-------- | :------------------------------------------------------------ | :---------------------------- |
| `id`      | `string`                                                      | The ID of the List to modify. |
| `options` | `UpdateOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[lists/client.ts:1610](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L1610)

▸ **update**(`id`, `options?`): `Promise`\<[`ListUpdateResponse`](/xdks/typescript/reference/interfaces/Schemas.ListUpdateResponse)>

#### Parameters

| Name       | Type            |
| :--------- | :-------------- |
| `id`       | `string`        |
| `options?` | `UpdateOptions` |

#### Returns

`Promise`\<[`ListUpdateResponse`](/xdks/typescript/reference/interfaces/Schemas.ListUpdateResponse)>

#### Defined in

[lists/client.ts:1623](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L1623)

***

### delete

▸ **delete**(`id`, `options`): `Promise`\<`Response`>

Delete List
Deletes a specific List owned by the authenticated user by its ID.

#### Parameters

| Name                         | Type     | Description                   |
| :--------------------------- | :------- | :---------------------------- |
| `id`                         | `string` | The ID of the List to delete. |
| `options`                    | `Object` | -                             |
| `options.requestOptions`     | `Object` | -                             |
| `options.requestOptions.raw` | `true`   | -                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[lists/client.ts:1731](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L1731)

▸ **delete**(`id`): `Promise`\<[`ListDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.ListDeleteResponse)>

#### Parameters

| Name | Type     |
| :--- | :------- |
| `id` | `string` |

#### Returns

`Promise`\<[`ListDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.ListDeleteResponse)>

#### Defined in

[lists/client.ts:1744](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/client.ts#L1744)


# MediaClient
Source: https://docs.x.com/xdks/typescript/reference/classes/MediaClient

Reference for the MediaClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 media endpoints.

Client for media operations

This client provides methods for interacting with the media endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all media related operations.

zeUpload]\(/xdks/typescript/reference/classes/MediaClient#finalizeupload)

* [initializeUpload](/xdks/typescript/reference/classes/MediaClient#initializeupload)
* [createSubtitles](/xdks/typescript/reference/classes/MediaClient#createsubtitles)
* [deleteSubtitles](/xdks/typescript/reference/classes/MediaClient#deletesubtitles)

## Constructors

### constructor

• **new MediaClient**(`client`): [`MediaClient`](/xdks/typescript/reference/classes/MediaClient)

Creates a new media client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`MediaClient`](/xdks/typescript/reference/classes/MediaClient)

#### Defined in

[media/client.ts:250](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L250)

## Methods

### getByKey

▸ **getByKey**(`mediaKey`, `options`): `Promise`\<`Response`>

Get Media by media key
Retrieves details of a specific Media file by its media key.

#### Parameters

| Name       | Type                                                            | Description         |
| :--------- | :-------------------------------------------------------------- | :------------------ |
| `mediaKey` | `string`                                                        | A single Media Key. |
| `options`  | `GetByKeyOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[media/client.ts:295](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L295)

▸ **getByKey**(`mediaKey`, `options?`): `Promise`\<[`Get2MediaMediaKeyResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2MediaMediaKeyResponse)>

#### Parameters

| Name       | Type              |
| :--------- | :---------------- |
| `mediaKey` | `string`          |
| `options?` | `GetByKeyOptions` |

#### Returns

`Promise`\<[`Get2MediaMediaKeyResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2MediaMediaKeyResponse)>

#### Defined in

[media/client.ts:308](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L308)

***

### getUploadStatus

▸ **getUploadStatus**(`mediaId`, `options`): `Promise`\<`Response`>

Get Media upload status
Retrieves the status of a Media upload by its ID.

#### Parameters

| Name      | Type                                                                   | Description                                     |
| :-------- | :--------------------------------------------------------------------- | :---------------------------------------------- |
| `mediaId` | `string`                                                               | Media id for the requested media upload status. |
| `options` | `GetUploadStatusOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                               |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[media/client.ts:442](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L442)

▸ **getUploadStatus**(`mediaId`, `options?`): `Promise`\<[`MediaUploadResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)>

#### Parameters

| Name       | Type                     |
| :--------- | :----------------------- |
| `mediaId`  | `string`                 |
| `options?` | `GetUploadStatusOptions` |

#### Returns

`Promise`\<[`MediaUploadResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)>

#### Defined in

[media/client.ts:455](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L455)

***

### upload

▸ **upload**(`options`): `Promise`\<`Response`>

Upload media
Uploads a media file for use in posts or other content.

#### Parameters

| Name      | Type                                                          |
| :-------- | :------------------------------------------------------------ |
| `options` | `UploadOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[media/client.ts:582](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L582)

▸ **upload**(`options?`): `Promise`\<[`MediaUploadResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)>

#### Parameters

| Name       | Type            |
| :--------- | :-------------- |
| `options?` | `UploadOptions` |

#### Returns

`Promise`\<[`MediaUploadResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)>

#### Defined in

[media/client.ts:591](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L591)

***

### getAnalytics

▸ **getAnalytics**(`mediaKeys`, `endTime`, `startTime`, `granularity`, `options`): `Promise`\<`Response`>

Get Media analytics
Retrieves analytics data for media.

#### Parameters

| Name          | Type                                                                | Description                                                                       |
| :------------ | :------------------------------------------------------------------ | :-------------------------------------------------------------------------------- |
| `mediaKeys`   | `any`\[]                                                            | A comma separated list of Media Keys. Up to 100 are allowed in a single request.  |
| `endTime`     | `string`                                                            | YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the end of the time range.   |
| `startTime`   | `string`                                                            | YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the start of the time range. |
| `granularity` | `string`                                                            | The granularity for the search counts results.                                    |
| `options`     | `GetAnalyticsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                 |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[media/client.ts:699](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L699)

▸ **getAnalytics**(`mediaKeys`, `endTime`, `startTime`, `granularity`, `options?`): `Promise`\<[`MediaAnalytics`](/xdks/typescript/reference/interfaces/Schemas.MediaAnalytics)>

#### Parameters

| Name          | Type                  |
| :------------ | :-------------------- |
| `mediaKeys`   | `any`\[]              |
| `endTime`     | `string`              |
| `startTime`   | `string`              |
| `granularity` | `string`              |
| `options?`    | `GetAnalyticsOptions` |

#### Returns

`Promise`\<[`MediaAnalytics`](/xdks/typescript/reference/interfaces/Schemas.MediaAnalytics)>

#### Defined in

[media/client.ts:724](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L724)

***

### appendUpload

▸ **appendUpload**(`id`, `options`): `Promise`\<`Response`>

Append Media upload
Appends data to a Media upload request.

#### Parameters

| Name      | Type                                                                | Description                                                         |
| :-------- | :------------------------------------------------------------------ | :------------------------------------------------------------------ |
| `id`      | `string`                                                            | The media identifier for the media to perform the append operation. |
| `options` | `AppendUploadOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[media/client.ts:918](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L918)

▸ **appendUpload**(`id`, `options?`): `Promise`\<[`MediaUploadAppendResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadAppendResponse)>

#### Parameters

| Name       | Type                  |
| :--------- | :-------------------- |
| `id`       | `string`              |
| `options?` | `AppendUploadOptions` |

#### Returns

`Promise`\<[`MediaUploadAppendResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadAppendResponse)>

#### Defined in

[media/client.ts:931](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L931)

***

### getByKeys

▸ **getByKeys**(`mediaKeys`, `options`): `Promise`\<`Response`>

Get Media by media keys
Retrieves details of Media files by their media keys.

#### Parameters

| Name        | Type                                                             | Description                                                                      |
| :---------- | :--------------------------------------------------------------- | :------------------------------------------------------------------------------- |
| `mediaKeys` | `any`\[]                                                         | A comma separated list of Media Keys. Up to 100 are allowed in a single request. |
| `options`   | `GetByKeysOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[media/client.ts:1039](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L1039)

▸ **getByKeys**(`mediaKeys`, `options?`): `Promise`\<[`Get2MediaResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2MediaResponse)>

#### Parameters

| Name        | Type               |
| :---------- | :----------------- |
| `mediaKeys` | `any`\[]           |
| `options?`  | `GetByKeysOptions` |

#### Returns

`Promise`\<[`Get2MediaResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2MediaResponse)>

#### Defined in

[media/client.ts:1052](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L1052)

***

### createMetadata

▸ **createMetadata**(`options`): `Promise`\<`Response`>

Create Media metadata
Creates metadata for a Media file.

#### Parameters

| Name      | Type                                                                  |
| :-------- | :-------------------------------------------------------------------- |
| `options` | `CreateMetadataOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[media/client.ts:1191](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L1191)

▸ **createMetadata**(`options?`): `Promise`\<[`MetadataCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.MetadataCreateResponse)>

#### Parameters

| Name       | Type                    |
| :--------- | :---------------------- |
| `options?` | `CreateMetadataOptions` |

#### Returns

`Promise`\<[`MetadataCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.MetadataCreateResponse)>

#### Defined in

[media/client.ts:1200](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L1200)

***

### finalizeUpload

▸ **finalizeUpload**(`id`, `options`): `Promise`\<`Response`>

Finalize Media upload
Finalizes a Media upload request.

#### Parameters

| Name                         | Type     | Description                                     |
| :--------------------------- | :------- | :---------------------------------------------- |
| `id`                         | `string` | The media id of the targeted media to finalize. |
| `options`                    | `Object` | -                                               |
| `options.requestOptions`     | `Object` | -                                               |
| `options.requestOptions.raw` | `true`   | -                                               |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[media/client.ts:1296](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L1296)

▸ **finalizeUpload**(`id`): `Promise`\<[`MediaUploadResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)>

#### Parameters

| Name | Type     |
| :--- | :------- |
| `id` | `string` |

#### Returns

`Promise`\<[`MediaUploadResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)>

#### Defined in

[media/client.ts:1309](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L1309)

***

### initializeUpload

▸ **initializeUpload**(`options`): `Promise`\<`Response`>

Initialize media upload
Initializes a media upload.

#### Parameters

| Name      | Type                                                                    |
| :-------- | :---------------------------------------------------------------------- |
| `options` | `InitializeUploadOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[media/client.ts:1396](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L1396)

▸ **initializeUpload**(`options?`): `Promise`\<[`MediaUploadResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)>

#### Parameters

| Name       | Type                      |
| :--------- | :------------------------ |
| `options?` | `InitializeUploadOptions` |

#### Returns

`Promise`\<[`MediaUploadResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)>

#### Defined in

[media/client.ts:1405](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L1405)

***

### createSubtitles

▸ **createSubtitles**(`options`): `Promise`\<`Response`>

Create Media subtitles
Creates subtitles for a specific Media file.

#### Parameters

| Name      | Type                                                                   |
| :-------- | :--------------------------------------------------------------------- |
| `options` | `CreateSubtitlesOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[media/client.ts:1497](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L1497)

▸ **createSubtitles**(`options?`): `Promise`\<[`SubtitlesCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateResponse)>

#### Parameters

| Name       | Type                     |
| :--------- | :----------------------- |
| `options?` | `CreateSubtitlesOptions` |

#### Returns

`Promise`\<[`SubtitlesCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateResponse)>

#### Defined in

[media/client.ts:1506](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L1506)

***

### deleteSubtitles

▸ **deleteSubtitles**(`options`): `Promise`\<`Response`>

Delete Media subtitles
Deletes subtitles for a specific Media file.

#### Parameters

| Name      | Type                                                                   |
| :-------- | :--------------------------------------------------------------------- |
| `options` | `DeleteSubtitlesOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[media/client.ts:1598](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L1598)

▸ **deleteSubtitles**(`options?`): `Promise`\<[`SubtitlesDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteResponse)>

#### Parameters

| Name       | Type                     |
| :--------- | :----------------------- |
| `options?` | `DeleteSubtitlesOptions` |

#### Returns

`Promise`\<[`SubtitlesDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteResponse)>

#### Defined in

[media/client.ts:1607](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/client.ts#L1607)


# NewsClient
Source: https://docs.x.com/xdks/typescript/reference/classes/NewsClient

Reference for the NewsClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 news endpoints.

Client for news operations

This client provides methods for interacting with the news endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all news related operations.

## Constructors

### constructor

• **new NewsClient**(`client`): [`NewsClient`](/xdks/typescript/reference/classes/NewsClient)

Creates a new news client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`NewsClient`](/xdks/typescript/reference/classes/NewsClient)

#### Defined in

[news/client.ts:96](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/news/client.ts#L96)

## Methods

### get

▸ **get**(`id`, `options`): `Promise`\<`Response`>

Get news stories by ID
Retrieves news story by its ID.

#### Parameters

| Name      | Type                                                       | Description               |
| :-------- | :--------------------------------------------------------- | :------------------------ |
| `id`      | `string`                                                   | The ID of the news story. |
| `options` | `GetOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                         |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[news/client.ts:141](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/news/client.ts#L141)

▸ **get**(`id`, `options?`): `Promise`\<[`Get2NewsIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2NewsIdResponse)>

#### Parameters

| Name       | Type         |
| :--------- | :----------- |
| `id`       | `string`     |
| `options?` | `GetOptions` |

#### Returns

`Promise`\<[`Get2NewsIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2NewsIdResponse)>

#### Defined in

[news/client.ts:154](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/news/client.ts#L154)

***

### search

▸ **search**(`query`, `options`): `Promise`\<`Response`>

Search News
Retrieves a list of News stories matching the specified search query.

#### Parameters

| Name      | Type                                                          | Description       |
| :-------- | :------------------------------------------------------------ | :---------------- |
| `query`   | `string`                                                      | The search query. |
| `options` | `SearchOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                 |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[news/client.ts:288](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/news/client.ts#L288)

▸ **search**(`query`, `options?`): `Promise`\<[`Get2NewsSearchResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2NewsSearchResponse)>

#### Parameters

| Name       | Type            |
| :--------- | :-------------- |
| `query`    | `string`        |
| `options?` | `SearchOptions` |

#### Returns

`Promise`\<[`Get2NewsSearchResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2NewsSearchResponse)>

#### Defined in

[news/client.ts:301](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/news/client.ts#L301)


# Paginator
Source: https://docs.x.com/xdks/typescript/reference/classes/Paginator

Reference for the Paginator class in the X API TypeScript SDK. Iterate paginated response results with async iterators and cursor helpers.

X API paginator with rich functionality

This class provides comprehensive pagination support for the X API, including:

* Automatic iteration with `for await...of` loops
* Manual page control with `fetchNext()` and `fetchPrevious()`
* Metadata access for pagination tokens and counts
* Error handling and rate limit detection
* Support for both forward and backward pagination

**`Example`**

```typescript title="Example" lines wrap icon="square-js" theme={null}
// Automatic iteration
const followers = await client.users.getFollowers('783214');
for await (const follower of followers) {
  console.log(follower.username);
}

// Manual control
const followers = await client.users.getFollowers('783214');
await followers.fetchNext();
console.log(followers.items.length); // Number of followers
console.log(followers.meta.nextToken); // Next page token

// Check status
if (!followers.done) {
  await followers.fetchNext();
}
```

## Type parameters

| Name | Description                       |
| :--- | :-------------------------------- |
| `T`  | The type of items being paginated |

## Hierarchy

* **`Paginator`**

  ↳ [`PostPaginator`](/xdks/typescript/reference/classes/PostPaginator)

  ↳ [`UserPaginator`](/xdks/typescript/reference/classes/UserPaginator)

  ↳ [`EventPaginator`](/xdks/typescript/reference/classes/EventPaginator)

## Implements

* `AsyncIterable`\<`T`>

## Constructors

### constructor

• **new Paginator**\<`T`>(`fetchPage`): [`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`T`>

Creates a new paginator instance

#### Type parameters

| Name |
| :--- |
| `T`  |

#### Parameters

| Name        | Type                                                                                                                     | Description                                                   |
| :---------- | :----------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
| `fetchPage` | (`token?`: `string`) => `Promise`\<[`PaginatedResponse`](/xdks/typescript/reference/interfaces/PaginatedResponse)\<`T`>> | Function that fetches a page of data given a pagination token |

#### Returns

[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`T`>

#### Defined in

[paginator.ts:90](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L90)

## Accessors

### items

• `get` **items**(): `T`\[]

Get all fetched items

#### Returns

`T`\[]

#### Defined in

[paginator.ts:97](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L97)

***

### meta

• `get` **meta**(): `any`

Get current pagination metadata

#### Returns

`any`

#### Defined in

[paginator.ts:104](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L104)

***

### includes

• `get` **includes**(): `undefined` | `Record`\<`string`, `any`>

Get current includes data

#### Returns

`undefined` | `Record`\<`string`, `any`>

#### Defined in

[paginator.ts:111](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L111)

***

### errors

• `get` **errors**(): `undefined` | `any`\[]

Get current errors

#### Returns

`undefined` | `any`\[]

#### Defined in

[paginator.ts:118](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L118)

***

### done

• `get` **done**(): `boolean`

Check if pagination is done

#### Returns

`boolean`

#### Defined in

[paginator.ts:125](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L125)

***

### rateLimited

• `get` **rateLimited**(): `boolean`

Check if rate limit was hit

#### Returns

`boolean`

#### Defined in

[paginator.ts:132](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L132)

## Methods

### fetchNext

▸ **fetchNext**(): `Promise`\<`void`>

Fetch the next page and add items to current instance

This method fetches the next page of data and appends the items to the
current paginator instance. It updates the pagination state and metadata.

#### Returns

`Promise`\<`void`>

**`Example`**

```typescript theme={null}
const followers = await client.users.getFollowers('783214');
await followers.fetchNext(); // Fetch first page
console.log(followers.items.length); // Number of followers

if (!followers.done) {
  await followers.fetchNext(); // Fetch second page
  console.log(followers.items.length); // Total followers across pages
}
```

**`Throws`**

When the API request fails

#### Defined in

[paginator.ts:156](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L156)

***

### next

▸ **next**(): `Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`T`>>

Get next page as a new instance

This method creates a new paginator instance that starts from the next page,
without affecting the current paginator's state.

#### Returns

`Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`T`>>

New paginator instance for the next page

**`Example`**

```typescript theme={null}
const followers = await client.users.getFollowers('783214');
await followers.fetchNext(); // Fetch first page

if (!followers.done) {
  const nextPage = await followers.next(); // Get next page as new instance
  console.log(followers.items.length); // Still first page
  console.log(nextPage.items.length); // Second page
}
```

#### Defined in

[paginator.ts:211](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L211)

***

### fetchPrevious

▸ **fetchPrevious**(): `Promise`\<`void`>

Fetch previous page (if supported)

#### Returns

`Promise`\<`void`>

#### Defined in

[paginator.ts:225](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L225)

***

### previous

▸ **previous**(): `Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`T`>>

Get previous page as a new instance

#### Returns

`Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`T`>>

#### Defined in

[paginator.ts:260](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L260)

***

### fetchLast

▸ **fetchLast**(`count`): `Promise`\<`void`>

Fetch up to a specified number of additional items

#### Parameters

| Name    | Type     |
| :------ | :------- |
| `count` | `number` |

#### Returns

`Promise`\<`void`>

#### Defined in

[paginator.ts:274](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L274)

***

### reset

▸ **reset**(): `void`

Reset paginator to initial state

#### Returns

`void`

#### Defined in

[paginator.ts:288](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L288)

***

### \[iterator]

▸ **\[iterator]**(): `Iterator`\<`T`, `any`, `undefined`>

Iterator for all fetched items

#### Returns

`Iterator`\<`T`, `any`, `undefined`>

#### Defined in

[paginator.ts:303](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L303)

***

### \[asyncIterator]

▸ **\[asyncIterator]**(): `AsyncIterator`\<`T`, `any`, `undefined`>

Async iterator that fetches pages automatically

#### Returns

`AsyncIterator`\<`T`, `any`, `undefined`>

#### Implementation of

AsyncIterable.\[asyncIterator]

#### Defined in

[paginator.ts:312](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L312)


# PostPaginator
Source: https://docs.x.com/xdks/typescript/reference/classes/PostPaginator

Reference for the PostPaginator class in the X API TypeScript SDK. Iterate paginated post results with async iterators and cursor helpers.

Paginator for posts

## Hierarchy

* [`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>

  ↳ **`PostPaginator`**

## Constructors

### constructor

• **new PostPaginator**(`fetchPage`): [`PostPaginator`](/xdks/typescript/reference/classes/PostPaginator)

Creates a new paginator instance

#### Parameters

| Name        | Type                                                                                                                       | Description                                                   |
| :---------- | :------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
| `fetchPage` | (`token?`: `string`) => `Promise`\<[`PaginatedResponse`](/xdks/typescript/reference/interfaces/PaginatedResponse)\<`any`>> | Function that fetches a page of data given a pagination token |

#### Returns

[`PostPaginator`](/xdks/typescript/reference/classes/PostPaginator)

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[constructor](/xdks/typescript/reference/classes/Paginator#constructor)

#### Defined in

[paginator.ts:90](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L90)

## Accessors

### items

• `get` **items**(): `T`\[]

Get all fetched items

#### Returns

`T`\[]

#### Inherited from

Paginator.items

#### Defined in

[paginator.ts:97](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L97)

***

### meta

• `get` **meta**(): `any`

Get current pagination metadata

#### Returns

`any`

#### Inherited from

Paginator.meta

#### Defined in

[paginator.ts:104](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L104)

***

### includes

• `get` **includes**(): `undefined` | `Record`\<`string`, `any`>

Get current includes data

#### Returns

`undefined` | `Record`\<`string`, `any`>

#### Inherited from

Paginator.includes

#### Defined in

[paginator.ts:111](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L111)

***

### errors

• `get` **errors**(): `undefined` | `any`\[]

Get current errors

#### Returns

`undefined` | `any`\[]

#### Inherited from

Paginator.errors

#### Defined in

[paginator.ts:118](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L118)

***

### done

• `get` **done**(): `boolean`

Check if pagination is done

#### Returns

`boolean`

#### Inherited from

Paginator.done

#### Defined in

[paginator.ts:125](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L125)

***

### rateLimited

• `get` **rateLimited**(): `boolean`

Check if rate limit was hit

#### Returns

`boolean`

#### Inherited from

Paginator.rateLimited

#### Defined in

[paginator.ts:132](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L132)

***

### posts

• `get` **posts**(): `any`\[]

#### Returns

`any`\[]

#### Defined in

[paginator.ts:342](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L342)

## Methods

### fetchNext

▸ **fetchNext**(): `Promise`\<`void`>

Fetch the next page and add items to current instance

This method fetches the next page of data and appends the items to the
current paginator instance. It updates the pagination state and metadata.

#### Returns

`Promise`\<`void`>

**`Example`**

```typescript theme={null}
const followers = await client.users.getFollowers('783214');
await followers.fetchNext(); // Fetch first page
console.log(followers.items.length); // Number of followers

if (!followers.done) {
  await followers.fetchNext(); // Fetch second page
  console.log(followers.items.length); // Total followers across pages
}
```

**`Throws`**

When the API request fails

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[fetchNext](/xdks/typescript/reference/classes/Paginator#fetchnext)

#### Defined in

[paginator.ts:156](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L156)

***

### next

▸ **next**(): `Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>>

Get next page as a new instance

This method creates a new paginator instance that starts from the next page,
without affecting the current paginator's state.

#### Returns

`Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>>

New paginator instance for the next page

**`Example`**

```typescript theme={null}
const followers = await client.users.getFollowers('783214');
await followers.fetchNext(); // Fetch first page

if (!followers.done) {
  const nextPage = await followers.next(); // Get next page as new instance
  console.log(followers.items.length); // Still first page
  console.log(nextPage.items.length); // Second page
}
```

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[next](/xdks/typescript/reference/classes/Paginator#next)

#### Defined in

[paginator.ts:211](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L211)

***

### fetchPrevious

▸ **fetchPrevious**(): `Promise`\<`void`>

Fetch previous page (if supported)

#### Returns

`Promise`\<`void`>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[fetchPrevious](/xdks/typescript/reference/classes/Paginator#fetchprevious)

#### Defined in

[paginator.ts:225](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L225)

***

### previous

▸ **previous**(): `Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>>

Get previous page as a new instance

#### Returns

`Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[previous](/xdks/typescript/reference/classes/Paginator#previous)

#### Defined in

[paginator.ts:260](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L260)

***

### fetchLast

▸ **fetchLast**(`count`): `Promise`\<`void`>

Fetch up to a specified number of additional items

#### Parameters

| Name    | Type     |
| :------ | :------- |
| `count` | `number` |

#### Returns

`Promise`\<`void`>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[fetchLast](/xdks/typescript/reference/classes/Paginator#fetchlast)

#### Defined in

[paginator.ts:274](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L274)

***

### reset

▸ **reset**(): `void`

Reset paginator to initial state

#### Returns

`void`

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[reset](/xdks/typescript/reference/classes/Paginator#reset)

#### Defined in

[paginator.ts:288](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L288)

***

### \[iterator]

▸ **\[iterator]**(): `Iterator`\<`any`, `any`, `undefined`>

Iterator for all fetched items

#### Returns

`Iterator`\<`any`, `any`, `undefined`>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[\[iterator\]](/xdks/typescript/reference/classes/Paginator#iterator)

#### Defined in

[paginator.ts:303](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L303)

***

### \[asyncIterator]

▸ **\[asyncIterator]**(): `AsyncIterator`\<`any`, `any`, `undefined`>

Async iterator that fetches pages automatically

#### Returns

`AsyncIterator`\<`any`, `any`, `undefined`>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[\[asyncIterator\]](/xdks/typescript/reference/classes/Paginator#asynciterator)

#### Defined in

[paginator.ts:312](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L312)


# PostsClient
Source: https://docs.x.com/xdks/typescript/reference/classes/PostsClient

Reference for the PostsClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 posts endpoints.

Client for posts operations

This client provides methods for interacting with the posts endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all posts related operations.

## Constructors

### constructor

• **new PostsClient**(`client`): [`PostsClient`](/xdks/typescript/reference/classes/PostsClient)

Creates a new posts client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`PostsClient`](/xdks/typescript/reference/classes/PostsClient)

#### Defined in

[posts/client.ts:789](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L789)

## Methods

### getInsights28hr

▸ **getInsights28hr**(`tweetIds`, `granularity`, `requestedMetrics`, `options`): `Promise`\<`Response`>

Get 28-hour Post insights
Retrieves engagement metrics for specified Posts over the last 28 hours.

#### Parameters

| Name               | Type                                                                   | Description                             |
| :----------------- | :--------------------------------------------------------------------- | :-------------------------------------- |
| `tweetIds`         | `any`\[]                                                               | List of PostIds for 28hr metrics.       |
| `granularity`      | `string`                                                               | granularity of metrics response.        |
| `requestedMetrics` | `any`\[]                                                               | request metrics for historical request. |
| `options`          | `GetInsights28hrOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                       |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:842](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L842)

▸ **getInsights28hr**(`tweetIds`, `granularity`, `requestedMetrics`, `options?`): `Promise`\<[`Get2Insights28hrResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2Insights28hrResponse)>

#### Parameters

| Name               | Type                     |
| :----------------- | :----------------------- |
| `tweetIds`         | `any`\[]                 |
| `granularity`      | `string`                 |
| `requestedMetrics` | `any`\[]                 |
| `options?`         | `GetInsights28hrOptions` |

#### Returns

`Promise`\<[`Get2Insights28hrResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2Insights28hrResponse)>

#### Defined in

[posts/client.ts:863](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L863)

***

### getAnalytics

▸ **getAnalytics**(`ids`, `endTime`, `startTime`, `granularity`, `options`): `Promise`\<`Response`>

Get Post analytics
Retrieves analytics data for specified Posts within a defined time range.

#### Parameters

| Name          | Type                                                                | Description                                                                       |
| :------------ | :------------------------------------------------------------------ | :-------------------------------------------------------------------------------- |
| `ids`         | `any`\[]                                                            | A comma separated list of Post IDs. Up to 100 are allowed in a single request.    |
| `endTime`     | `string`                                                            | YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the end of the time range.   |
| `startTime`   | `string`                                                            | YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the start of the time range. |
| `granularity` | `string`                                                            | The granularity for the search counts results.                                    |
| `options`     | `GetAnalyticsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                 |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:1052](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L1052)

▸ **getAnalytics**(`ids`, `endTime`, `startTime`, `granularity`, `options?`): `Promise`\<[`Analytics`](/xdks/typescript/reference/interfaces/Schemas.Analytics)>

#### Parameters

| Name          | Type                  |
| :------------ | :-------------------- |
| `ids`         | `any`\[]              |
| `endTime`     | `string`              |
| `startTime`   | `string`              |
| `granularity` | `string`              |
| `options?`    | `GetAnalyticsOptions` |

#### Returns

`Promise`\<[`Analytics`](/xdks/typescript/reference/interfaces/Schemas.Analytics)>

#### Defined in

[posts/client.ts:1077](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L1077)

***

### getReposts

▸ **getReposts**(`id`, `options`): `Promise`\<`Response`>

Get Reposts
Retrieves a list of Posts that repost a specific Post by its ID.

#### Parameters

| Name      | Type                                                              | Description       |
| :-------- | :---------------------------------------------------------------- | :---------------- |
| `id`      | `string`                                                          | A single Post ID. |
| `options` | `GetRepostsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                 |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:1271](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L1271)

▸ **getReposts**(`id`, `options?`): `Promise`\<[`Get2TweetsIdRetweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetsResponse)>

#### Parameters

| Name       | Type                |
| :--------- | :------------------ |
| `id`       | `string`            |
| `options?` | `GetRepostsOptions` |

#### Returns

`Promise`\<[`Get2TweetsIdRetweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetsResponse)>

#### Defined in

[posts/client.ts:1284](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L1284)

***

### searchRecent

▸ **searchRecent**(`query`, `options`): `Promise`\<`Response`>

Search recent Posts
Retrieves Posts from the last 7 days matching a search query.

#### Parameters

| Name      | Type                                                                | Description                                                                                                                             |
| :-------- | :------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------- |
| `query`   | `string`                                                            | One query/rule/filter for matching Posts. Refer to [https://t.co/rulelength](https://t.co/rulelength) to identify the max query length. |
| `options` | `SearchRecentOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                                                                       |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:1559](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L1559)

▸ **searchRecent**(`query`, `options?`): `Promise`\<[`Get2TweetsSearchRecentResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchRecentResponse)>

#### Parameters

| Name       | Type                  |
| :--------- | :-------------------- |
| `query`    | `string`              |
| `options?` | `SearchRecentOptions` |

#### Returns

`Promise`\<[`Get2TweetsSearchRecentResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchRecentResponse)>

#### Defined in

[posts/client.ts:1572](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L1572)

***

### searchAll

▸ **searchAll**(`query`, `options`): `Promise`\<`Response`>

Search all Posts
Retrieves Posts from the full archive matching a search query.

#### Parameters

| Name      | Type                                                             | Description                                                                                                                             |
| :-------- | :--------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| `query`   | `string`                                                         | One query/rule/filter for matching Posts. Refer to [https://t.co/rulelength](https://t.co/rulelength) to identify the max query length. |
| `options` | `SearchAllOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                                                                       |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:1968](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L1968)

▸ **searchAll**(`query`, `options?`): `Promise`\<[`Get2TweetsSearchAllResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchAllResponse)>

#### Parameters

| Name       | Type               |
| :--------- | :----------------- |
| `query`    | `string`           |
| `options?` | `SearchAllOptions` |

#### Returns

`Promise`\<[`Get2TweetsSearchAllResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchAllResponse)>

#### Defined in

[posts/client.ts:1981](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L1981)

***

### getByIds

▸ **getByIds**(`ids`, `options`): `Promise`\<`Response`>

Get Posts by IDs
Retrieves details of multiple Posts by their IDs.

#### Parameters

| Name      | Type                                                            | Description                                                                    |
| :-------- | :-------------------------------------------------------------- | :----------------------------------------------------------------------------- |
| `ids`     | `any`\[]                                                        | A comma separated list of Post IDs. Up to 100 are allowed in a single request. |
| `options` | `GetByIdsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                              |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:2365](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L2365)

▸ **getByIds**(`ids`, `options?`): `Promise`\<[`Get2TweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsResponse)>

#### Parameters

| Name       | Type              |
| :--------- | :---------------- |
| `ids`      | `any`\[]          |
| `options?` | `GetByIdsOptions` |

#### Returns

`Promise`\<[`Get2TweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsResponse)>

#### Defined in

[posts/client.ts:2378](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L2378)

***

### create

▸ **create**(`body`, `options`): `Promise`\<`Response`>

Create or Edit Post
Creates a new Post for the authenticated user, or edits an existing Post when edit\_options are provided.

#### Parameters

| Name                         | Type                                                                                     | Description  |
| :--------------------------- | :--------------------------------------------------------------------------------------- | :----------- |
| `body`                       | [`TweetCreateRequest`](/xdks/typescript/reference/interfaces/Schemas.TweetCreateRequest) | Request body |
| `options`                    | `Object`                                                                                 | -            |
| `options.requestOptions`     | `Object`                                                                                 | -            |
| `options.requestOptions.raw` | `true`                                                                                   | -            |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:2622](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L2622)

▸ **create**(`body`): `Promise`\<[`TweetCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.TweetCreateResponse)>

#### Parameters

| Name   | Type                                                                                     |
| :----- | :--------------------------------------------------------------------------------------- |
| `body` | [`TweetCreateRequest`](/xdks/typescript/reference/interfaces/Schemas.TweetCreateRequest) |

#### Returns

`Promise`\<[`TweetCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.TweetCreateResponse)>

#### Defined in

[posts/client.ts:2633](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L2633)

***

### getQuoted

▸ **getQuoted**(`id`, `options`): `Promise`\<`Response`>

Get Quoted Posts
Retrieves a list of Posts that quote a specific Post by its ID.

#### Parameters

| Name      | Type                                                             | Description       |
| :-------- | :--------------------------------------------------------------- | :---------------- |
| `id`      | `string`                                                         | A single Post ID. |
| `options` | `GetQuotedOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                 |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:2718](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L2718)

▸ **getQuoted**(`id`, `options?`): `Promise`\<[`Get2TweetsIdQuoteTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdQuoteTweetsResponse)>

#### Parameters

| Name       | Type               |
| :--------- | :----------------- |
| `id`       | `string`           |
| `options?` | `GetQuotedOptions` |

#### Returns

`Promise`\<[`Get2TweetsIdQuoteTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdQuoteTweetsResponse)>

#### Defined in

[posts/client.ts:2731](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L2731)

***

### getCountsRecent

▸ **getCountsRecent**(`query`, `options`): `Promise`\<`Response`>

Get count of recent Posts
Retrieves the count of Posts from the last 7 days matching a search query.

#### Parameters

| Name      | Type                                                                   | Description                                                                                                                             |
| :-------- | :--------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| `query`   | `string`                                                               | One query/rule/filter for matching Posts. Refer to [https://t.co/rulelength](https://t.co/rulelength) to identify the max query length. |
| `options` | `GetCountsRecentOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                                                                       |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:3025](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L3025)

▸ **getCountsRecent**(`query`, `options?`): `Promise`\<[`Get2TweetsCountsRecentResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsRecentResponse)>

#### Parameters

| Name       | Type                     |
| :--------- | :----------------------- |
| `query`    | `string`                 |
| `options?` | `GetCountsRecentOptions` |

#### Returns

`Promise`\<[`Get2TweetsCountsRecentResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsRecentResponse)>

#### Defined in

[posts/client.ts:3038](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L3038)

***

### hideReply

▸ **hideReply**(`tweetId`, `options`): `Promise`\<`Response`>

Hide reply
Hides or unhides a reply to a conversation owned by the authenticated user.

#### Parameters

| Name      | Type                                                             | Description                                          |
| :-------- | :--------------------------------------------------------------- | :--------------------------------------------------- |
| `tweetId` | `string`                                                         | The ID of the reply that you want to hide or unhide. |
| `options` | `HideReplyOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                    |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:3298](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L3298)

▸ **hideReply**(`tweetId`, `options?`): `Promise`\<[`TweetHideResponse`](/xdks/typescript/reference/interfaces/Schemas.TweetHideResponse)>

#### Parameters

| Name       | Type               |
| :--------- | :----------------- |
| `tweetId`  | `string`           |
| `options?` | `HideReplyOptions` |

#### Returns

`Promise`\<[`TweetHideResponse`](/xdks/typescript/reference/interfaces/Schemas.TweetHideResponse)>

#### Defined in

[posts/client.ts:3311](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L3311)

***

### getInsightsHistorical

▸ **getInsightsHistorical**(`tweetIds`, `endTime`, `startTime`, `granularity`, `requestedMetrics`, `options`): `Promise`\<`Response`>

Get historical Post insights
Retrieves historical engagement metrics for specified Posts within a defined time range.

#### Parameters

| Name               | Type                                                                         | Description                                                                       |
| :----------------- | :--------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| `tweetIds`         | `any`\[]                                                                     | List of PostIds for historical metrics.                                           |
| `endTime`          | `string`                                                                     | YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the end of the time range.   |
| `startTime`        | `string`                                                                     | YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the start of the time range. |
| `granularity`      | `string`                                                                     | granularity of metrics response.                                                  |
| `requestedMetrics` | `any`\[]                                                                     | request metrics for historical request.                                           |
| `options`          | `GetInsightsHistoricalOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                 |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:3435](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L3435)

▸ **getInsightsHistorical**(`tweetIds`, `endTime`, `startTime`, `granularity`, `requestedMetrics`, `options?`): `Promise`\<[`Get2InsightsHistoricalResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2InsightsHistoricalResponse)>

#### Parameters

| Name               | Type                           |
| :----------------- | :----------------------------- |
| `tweetIds`         | `any`\[]                       |
| `endTime`          | `string`                       |
| `startTime`        | `string`                       |
| `granularity`      | `string`                       |
| `requestedMetrics` | `any`\[]                       |
| `options?`         | `GetInsightsHistoricalOptions` |

#### Returns

`Promise`\<[`Get2InsightsHistoricalResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2InsightsHistoricalResponse)>

#### Defined in

[posts/client.ts:3464](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L3464)

***

### getCountsAll

▸ **getCountsAll**(`query`, `options`): `Promise`\<`Response`>

Get count of all Posts
Retrieves the count of Posts matching a search query from the full archive.

#### Parameters

| Name      | Type                                                                | Description                                                                                                                             |
| :-------- | :------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------- |
| `query`   | `string`                                                            | One query/rule/filter for matching Posts. Refer to [https://t.co/rulelength](https://t.co/rulelength) to identify the max query length. |
| `options` | `GetCountsAllOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                                                                       |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:3679](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L3679)

▸ **getCountsAll**(`query`, `options?`): `Promise`\<[`Get2TweetsCountsAllResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsAllResponse)>

#### Parameters

| Name       | Type                  |
| :--------- | :-------------------- |
| `query`    | `string`              |
| `options?` | `GetCountsAllOptions` |

#### Returns

`Promise`\<[`Get2TweetsCountsAllResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsAllResponse)>

#### Defined in

[posts/client.ts:3692](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L3692)

***

### getById

▸ **getById**(`id`, `options`): `Promise`\<`Response`>

Get Post by ID
Retrieves details of a specific Post by its ID.

#### Parameters

| Name      | Type                                                           | Description       |
| :-------- | :------------------------------------------------------------- | :---------------- |
| `id`      | `string`                                                       | A single Post ID. |
| `options` | `GetByIdOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                 |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:3952](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L3952)

▸ **getById**(`id`, `options?`): `Promise`\<[`Get2TweetsIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdResponse)>

#### Parameters

| Name       | Type             |
| :--------- | :--------------- |
| `id`       | `string`         |
| `options?` | `GetByIdOptions` |

#### Returns

`Promise`\<[`Get2TweetsIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdResponse)>

#### Defined in

[posts/client.ts:3965](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L3965)

***

### delete

▸ **delete**(`id`, `options`): `Promise`\<`Response`>

Delete Post
Deletes a specific Post by its ID, if owned by the authenticated user.

#### Parameters

| Name                         | Type     | Description                       |
| :--------------------------- | :------- | :-------------------------------- |
| `id`                         | `string` | The ID of the Post to be deleted. |
| `options`                    | `Object` | -                                 |
| `options.requestOptions`     | `Object` | -                                 |
| `options.requestOptions.raw` | `true`   | -                                 |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:4202](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L4202)

▸ **delete**(`id`): `Promise`\<[`TweetDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.TweetDeleteResponse)>

#### Parameters

| Name | Type     |
| :--- | :------- |
| `id` | `string` |

#### Returns

`Promise`\<[`TweetDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.TweetDeleteResponse)>

#### Defined in

[posts/client.ts:4215](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L4215)

***

### getLikingUsers

▸ **getLikingUsers**(`id`, `options`): `Promise`\<`Response`>

Get Liking Users
Retrieves a list of Users who liked a specific Post by its ID.

#### Parameters

| Name      | Type                                                                  | Description       |
| :-------- | :-------------------------------------------------------------------- | :---------------- |
| `id`      | `string`                                                              | A single Post ID. |
| `options` | `GetLikingUsersOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                 |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:4306](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L4306)

▸ **getLikingUsers**(`id`, `options?`): `Promise`\<[`Get2TweetsIdLikingUsersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdLikingUsersResponse)>

#### Parameters

| Name       | Type                    |
| :--------- | :---------------------- |
| `id`       | `string`                |
| `options?` | `GetLikingUsersOptions` |

#### Returns

`Promise`\<[`Get2TweetsIdLikingUsersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdLikingUsersResponse)>

#### Defined in

[posts/client.ts:4319](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L4319)

***

### getRepostedBy

▸ **getRepostedBy**(`id`, `options`): `Promise`\<`Response`>

Get Reposted by
Retrieves a list of Users who reposted a specific Post by its ID.

#### Parameters

| Name      | Type                                                                 | Description       |
| :-------- | :------------------------------------------------------------------- | :---------------- |
| `id`      | `string`                                                             | A single Post ID. |
| `options` | `GetRepostedByOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                 |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[posts/client.ts:4525](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L4525)

▸ **getRepostedBy**(`id`, `options?`): `Promise`\<[`Get2TweetsIdRetweetedByResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetedByResponse)>

#### Parameters

| Name       | Type                   |
| :--------- | :--------------------- |
| `id`       | `string`               |
| `options?` | `GetRepostedByOptions` |

#### Returns

`Promise`\<[`Get2TweetsIdRetweetedByResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetedByResponse)>

#### Defined in

[posts/client.ts:4538](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/client.ts#L4538)


# SpacesClient
Source: https://docs.x.com/xdks/typescript/reference/classes/SpacesClient

Reference for the SpacesClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 spaces endpoints.

Client for spaces operations

This client provides methods for interacting with the spaces endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all spaces related operations.

## Constructors

### constructor

• **new SpacesClient**(`client`): [`SpacesClient`](/xdks/typescript/reference/classes/SpacesClient)

Creates a new spaces client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`SpacesClient`](/xdks/typescript/reference/classes/SpacesClient)

#### Defined in

[spaces/client.ts:316](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L316)

## Methods

### getByIds

▸ **getByIds**(`ids`, `options`): `Promise`\<`Response`>

Get Spaces by IDs
Retrieves details of multiple Spaces by their IDs.

#### Parameters

| Name      | Type                                                            | Description                      |
| :-------- | :-------------------------------------------------------------- | :------------------------------- |
| `ids`     | `any`\[]                                                        | The list of Space IDs to return. |
| `options` | `GetByIdsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[spaces/client.ts:361](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L361)

▸ **getByIds**(`ids`, `options?`): `Promise`\<[`Get2SpacesResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesResponse)>

#### Parameters

| Name       | Type              |
| :--------- | :---------------- |
| `ids`      | `any`\[]          |
| `options?` | `GetByIdsOptions` |

#### Returns

`Promise`\<[`Get2SpacesResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesResponse)>

#### Defined in

[spaces/client.ts:374](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L374)

***

### getPosts

▸ **getPosts**(`id`, `options`): `Promise`\<`Response`>

Get Space Posts
Retrieves a list of Posts shared in a specific Space by its ID.

#### Parameters

| Name      | Type                                                            | Description                          |
| :-------- | :-------------------------------------------------------------- | :----------------------------------- |
| `id`      | `string`                                                        | The ID of the Space to be retrieved. |
| `options` | `GetPostsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                    |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[spaces/client.ts:572](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L572)

▸ **getPosts**(`id`, `options?`): `Promise`\<[`Get2SpacesIdTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdTweetsResponse)>

#### Parameters

| Name       | Type              |
| :--------- | :---------------- |
| `id`       | `string`          |
| `options?` | `GetPostsOptions` |

#### Returns

`Promise`\<[`Get2SpacesIdTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdTweetsResponse)>

#### Defined in

[spaces/client.ts:585](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L585)

***

### search

▸ **search**(`query`, `options`): `Promise`\<`Response`>

Search Spaces
Retrieves a list of Spaces matching the specified search query.

#### Parameters

| Name      | Type                                                          | Description       |
| :-------- | :------------------------------------------------------------ | :---------------- |
| `query`   | `string`                                                      | The search query. |
| `options` | `SearchOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                 |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[spaces/client.ts:835](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L835)

▸ **search**(`query`, `options?`): `Promise`\<[`Get2SpacesSearchResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesSearchResponse)>

#### Parameters

| Name       | Type            |
| :--------- | :-------------- |
| `query`    | `string`        |
| `options?` | `SearchOptions` |

#### Returns

`Promise`\<[`Get2SpacesSearchResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesSearchResponse)>

#### Defined in

[spaces/client.ts:848](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L848)

***

### getBuyers

▸ **getBuyers**(`id`, `options`): `Promise`\<`Response`>

Get Space ticket buyers
Retrieves a list of Users who purchased tickets to a specific Space by its ID.

#### Parameters

| Name      | Type                                                             | Description                          |
| :-------- | :--------------------------------------------------------------- | :----------------------------------- |
| `id`      | `string`                                                         | The ID of the Space to be retrieved. |
| `options` | `GetBuyersOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                    |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[spaces/client.ts:1080](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L1080)

▸ **getBuyers**(`id`, `options?`): `Promise`\<[`Get2SpacesIdBuyersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdBuyersResponse)>

#### Parameters

| Name       | Type               |
| :--------- | :----------------- |
| `id`       | `string`           |
| `options?` | `GetBuyersOptions` |

#### Returns

`Promise`\<[`Get2SpacesIdBuyersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdBuyersResponse)>

#### Defined in

[spaces/client.ts:1093](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L1093)

***

### getById

▸ **getById**(`id`, `options`): `Promise`\<`Response`>

Get space by ID
Retrieves details of a specific space by its ID.

#### Parameters

| Name      | Type                                                           | Description                          |
| :-------- | :------------------------------------------------------------- | :----------------------------------- |
| `id`      | `string`                                                       | The ID of the Space to be retrieved. |
| `options` | `GetByIdOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                    |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[spaces/client.ts:1293](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L1293)

▸ **getById**(`id`, `options?`): `Promise`\<[`Get2SpacesIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdResponse)>

#### Parameters

| Name       | Type             |
| :--------- | :--------------- |
| `id`       | `string`         |
| `options?` | `GetByIdOptions` |

#### Returns

`Promise`\<[`Get2SpacesIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdResponse)>

#### Defined in

[spaces/client.ts:1306](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L1306)

***

### getByCreatorIds

▸ **getByCreatorIds**(`userIds`, `options`): `Promise`\<`Response`>

Get Spaces by creator IDs
Retrieves details of Spaces created by specified User IDs.

#### Parameters

| Name      | Type                                                                   | Description                         |
| :-------- | :--------------------------------------------------------------------- | :---------------------------------- |
| `userIds` | `any`\[]                                                               | The IDs of Users to search through. |
| `options` | `GetByCreatorIdsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[spaces/client.ts:1495](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L1495)

▸ **getByCreatorIds**(`userIds`, `options?`): `Promise`\<[`Get2SpacesByCreatorIdsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesByCreatorIdsResponse)>

#### Parameters

| Name       | Type                     |
| :--------- | :----------------------- |
| `userIds`  | `any`\[]                 |
| `options?` | `GetByCreatorIdsOptions` |

#### Returns

`Promise`\<[`Get2SpacesByCreatorIdsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesByCreatorIdsResponse)>

#### Defined in

[spaces/client.ts:1508](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/client.ts#L1508)


# StreamClient
Source: https://docs.x.com/xdks/typescript/reference/classes/StreamClient

Reference for the StreamClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 stream endpoints.

## Constructors

### constructor

• **new StreamClient**(`client`): [`StreamClient`](/xdks/typescript/reference/classes/StreamClient)

#### Parameters

| Name     | Type                                                  |
| :------- | :---------------------------------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) |

#### Returns

[`StreamClient`](/xdks/typescript/reference/classes/StreamClient)

#### Defined in

[stream/stream\_client.ts:972](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L972)

## Methods

### likesCompliance

▸ **likesCompliance**(`options?`): `Promise`\<`EventDrivenStream`>

Stream Likes compliance data
Streams all compliance data related to Likes for Users.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name      | Type                              |
| :-------- | :-------------------------------- |
| `options` | `LikesComplianceStreamingOptions` |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:1016](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L1016)

***

### usersCompliance

▸ **usersCompliance**(`partition`, `options?`): `Promise`\<`EventDrivenStream`>

Stream Users compliance data
Streams all compliance data related to Users.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name        | Type                              | Description           |
| :---------- | :-------------------------------- | :-------------------- |
| `partition` | `number`                          | The partition number. |
| `options`   | `UsersComplianceStreamingOptions` | -                     |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:1196](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L1196)

***

### postsFirehoseKo

▸ **postsFirehoseKo**(`partition`, `options?`): `Promise`\<`EventDrivenStream`>

Stream Korean Posts
Streams all public Korean-language Posts in real-time.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name        | Type                              | Description           |
| :---------- | :-------------------------------- | :-------------------- |
| `partition` | `number`                          | The partition number. |
| `options`   | `PostsFirehoseKoStreamingOptions` | -                     |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:1392](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L1392)

***

### likesSample10

▸ **likesSample10**(`partition`, `options?`): `Promise`\<`EventDrivenStream`>

Stream sampled Likes
Streams a 10% sample of public Likes in real-time.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name        | Type                            | Description           |
| :---------- | :------------------------------ | :-------------------- |
| `partition` | `number`                        | The partition number. |
| `options`   | `LikesSample10StreamingOptions` | -                     |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:1706](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L1706)

***

### likesFirehose

▸ **likesFirehose**(`partition`, `options?`): `Promise`\<`EventDrivenStream`>

Stream all Likes
Streams all public Likes in real-time.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name        | Type                            | Description           |
| :---------- | :------------------------------ | :-------------------- |
| `partition` | `number`                        | The partition number. |
| `options`   | `LikesFirehoseStreamingOptions` | -                     |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:1983](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L1983)

***

### postsFirehoseJa

▸ **postsFirehoseJa**(`partition`, `options?`): `Promise`\<`EventDrivenStream`>

Stream Japanese Posts
Streams all public Japanese-language Posts in real-time.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name        | Type                              | Description           |
| :---------- | :-------------------------------- | :-------------------- |
| `partition` | `number`                          | The partition number. |
| `options`   | `PostsFirehoseJaStreamingOptions` | -                     |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:2257](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L2257)

***

### postsFirehoseEn

▸ **postsFirehoseEn**(`partition`, `options?`): `Promise`\<`EventDrivenStream`>

Stream English Posts
Streams all public English-language Posts in real-time.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name        | Type                              | Description           |
| :---------- | :-------------------------------- | :-------------------- |
| `partition` | `number`                          | The partition number. |
| `options`   | `PostsFirehoseEnStreamingOptions` | -                     |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:2571](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L2571)

***

### postsSample

▸ **postsSample**(`options?`): `Promise`\<`EventDrivenStream`>

Stream sampled Posts
Streams a 1% sample of public Posts in real-time.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name      | Type                          |
| :-------- | :---------------------------- |
| `options` | `PostsSampleStreamingOptions` |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:2887](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L2887)

***

### postsSample10

▸ **postsSample10**(`partition`, `options?`): `Promise`\<`EventDrivenStream`>

Stream 10% sampled Posts
Streams a 10% sample of public Posts in real-time.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name        | Type                            | Description           |
| :---------- | :------------------------------ | :-------------------- |
| `partition` | `number`                        | The partition number. |
| `options`   | `PostsSample10StreamingOptions` | -                     |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:3145](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L3145)

***

### postsCompliance

▸ **postsCompliance**(`partition`, `options?`): `Promise`\<`EventDrivenStream`>

Stream Posts compliance data
Streams all compliance data related to Posts.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name        | Type                              | Description           |
| :---------- | :-------------------------------- | :-------------------- |
| `partition` | `number`                          | The partition number. |
| `options`   | `PostsComplianceStreamingOptions` | -                     |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:3459](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L3459)

***

### labelsCompliance

▸ **labelsCompliance**(`options?`): `Promise`\<`EventDrivenStream`>

Stream Post labels
Streams all labeling events applied to Posts.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name      | Type                               |
| :-------- | :--------------------------------- |
| `options` | `LabelsComplianceStreamingOptions` |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:3651](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L3651)

***

### posts

▸ **posts**(`options?`): `Promise`\<`EventDrivenStream`>

Stream filtered Posts
Streams Posts in real-time matching the active rule set.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name      | Type                    |
| :-------- | :---------------------- |
| `options` | `PostsStreamingOptions` |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:3827](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L3827)

***

### postsFirehose

▸ **postsFirehose**(`partition`, `options?`): `Promise`\<`EventDrivenStream`>

Stream all Posts
Streams all public Posts in real-time.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name        | Type                            | Description           |
| :---------- | :------------------------------ | :-------------------- |
| `partition` | `number`                        | The partition number. |
| `options`   | `PostsFirehoseStreamingOptions` | -                     |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:4125](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L4125)

***

### postsFirehosePt

▸ **postsFirehosePt**(`partition`, `options?`): `Promise`\<`EventDrivenStream`>

Stream Portuguese Posts
Streams all public Portuguese-language Posts in real-time.

Returns an event-driven stream that's easy to use.
Use .on() to listen for events like 'data', 'error', 'close'.
Also supports async iteration with for await...of.

#### Parameters

| Name        | Type                              | Description           |
| :---------- | :-------------------------------- | :-------------------- |
| `partition` | `number`                          | The partition number. |
| `options`   | `PostsFirehosePtStreamingOptions` | -                     |

#### Returns

`Promise`\<`EventDrivenStream`>

Event-driven stream for handling streaming data

#### Defined in

[stream/stream\_client.ts:4439](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L4439)

***

### getRuleCounts

▸ **getRuleCounts**(`options?`): `Promise`\<[`Get2TweetsSearchStreamRulesCountsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchStreamRulesCountsResponse)>

Get stream rule counts
Retrieves the count of rules in the active rule set for the filtered stream.

#### Parameters

| Name      | Type                            |
| :-------- | :------------------------------ |
| `options` | `GetRuleCountsStreamingOptions` |

#### Returns

`Promise`\<[`Get2TweetsSearchStreamRulesCountsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchStreamRulesCountsResponse)>

Promise with the API response

#### Defined in

[stream/stream\_client.ts:4753](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L4753)

***

### getRules

▸ **getRules**(`options?`): `Promise`\<[`RulesLookupResponse`](/xdks/typescript/reference/interfaces/Schemas.RulesLookupResponse)>

Get stream rules
Retrieves the active rule set or a subset of rules for the filtered stream.

#### Parameters

| Name      | Type                       |
| :-------- | :------------------------- |
| `options` | `GetRulesStreamingOptions` |

#### Returns

`Promise`\<[`RulesLookupResponse`](/xdks/typescript/reference/interfaces/Schemas.RulesLookupResponse)>

Promise with the API response

#### Defined in

[stream/stream\_client.ts:4854](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L4854)

***

### updateRules

▸ **updateRules**(`body`, `options?`): `Promise`\<[`AddOrDeleteRulesResponse`](/xdks/typescript/reference/interfaces/Schemas.AddOrDeleteRulesResponse)>

Update stream rules
Adds or deletes rules from the active rule set for the filtered stream.

#### Parameters

| Name      | Type                          |
| :-------- | :---------------------------- |
| `body`    | `any`                         |
| `options` | `UpdateRulesStreamingOptions` |

#### Returns

`Promise`\<[`AddOrDeleteRulesResponse`](/xdks/typescript/reference/interfaces/Schemas.AddOrDeleteRulesResponse)>

Promise with the API response

#### Defined in

[stream/stream\_client.ts:4987](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/stream_client.ts#L4987)


# TrendsClient
Source: https://docs.x.com/xdks/typescript/reference/classes/TrendsClient

Reference for the TrendsClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 trends endpoints.

Client for trends operations

This client provides methods for interacting with the trends endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all trends related operations.

zed]\(/xdks/typescript/reference/classes/TrendsClient#getpersonalized)

## Constructors

### constructor

• **new TrendsClient**(`client`): [`TrendsClient`](/xdks/typescript/reference/classes/TrendsClient)

Creates a new trends client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`TrendsClient`](/xdks/typescript/reference/classes/TrendsClient)

#### Defined in

[trends/client.ts:90](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/trends/client.ts#L90)

## Methods

### getByWoeid

▸ **getByWoeid**(`woeid`, `options`): `Promise`\<`Response`>

Get Trends by WOEID
Retrieves trending topics for a specific location identified by its WOEID.

#### Parameters

| Name      | Type                                                              | Description                                   |
| :-------- | :---------------------------------------------------------------- | :-------------------------------------------- |
| `woeid`   | `number`                                                          | The WOEID of the place to lookup a trend for. |
| `options` | `GetByWoeidOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[trends/client.ts:135](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/trends/client.ts#L135)

▸ **getByWoeid**(`woeid`, `options?`): `Promise`\<[`Get2TrendsByWoeidWoeidResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TrendsByWoeidWoeidResponse)>

#### Parameters

| Name       | Type                |
| :--------- | :------------------ |
| `woeid`    | `number`            |
| `options?` | `GetByWoeidOptions` |

#### Returns

`Promise`\<[`Get2TrendsByWoeidWoeidResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TrendsByWoeidWoeidResponse)>

#### Defined in

[trends/client.ts:148](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/trends/client.ts#L148)

***

### getPersonalized

▸ **getPersonalized**(`options`): `Promise`\<`Response`>

Get personalized Trends
Retrieves personalized trending topics for the authenticated user.

#### Parameters

| Name      | Type                                                                   |
| :-------- | :--------------------------------------------------------------------- |
| `options` | `GetPersonalizedOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[trends/client.ts:285](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/trends/client.ts#L285)

▸ **getPersonalized**(`options?`): `Promise`\<[`Get2UsersPersonalizedTrendsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersPersonalizedTrendsResponse)>

#### Parameters

| Name       | Type                     |
| :--------- | :----------------------- |
| `options?` | `GetPersonalizedOptions` |

#### Returns

`Promise`\<[`Get2UsersPersonalizedTrendsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersPersonalizedTrendsResponse)>

#### Defined in

[trends/client.ts:294](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/trends/client.ts#L294)


# UsageClient
Source: https://docs.x.com/xdks/typescript/reference/classes/UsageClient

Reference for the UsageClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 usage endpoints.

Client for usage operations

This client provides methods for interacting with the usage endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all usage related operations.

## Constructors

### constructor

• **new UsageClient**(`client`): [`UsageClient`](/xdks/typescript/reference/classes/UsageClient)

Creates a new usage client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`UsageClient`](/xdks/typescript/reference/classes/UsageClient)

#### Defined in

[usage/client.ts:68](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/usage/client.ts#L68)

## Methods

### get

▸ **get**(`options`): `Promise`\<`Response`>

Get usage
Retrieves usage statistics for Posts over a specified number of days.

#### Parameters

| Name      | Type                                                       |
| :-------- | :--------------------------------------------------------- |
| `options` | `GetOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[usage/client.ts:109](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/usage/client.ts#L109)

▸ **get**(`options?`): `Promise`\<[`Get2UsageTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsageTweetsResponse)>

#### Parameters

| Name       | Type         |
| :--------- | :----------- |
| `options?` | `GetOptions` |

#### Returns

`Promise`\<[`Get2UsageTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsageTweetsResponse)>

#### Defined in

[usage/client.ts:118](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/usage/client.ts#L118)


# UserPaginator
Source: https://docs.x.com/xdks/typescript/reference/classes/UserPaginator

Reference for the UserPaginator class in the X API TypeScript SDK. Iterate paginated user results with async iterators and cursor helpers.

Paginator for users

## Hierarchy

* [`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>

  ↳ **`UserPaginator`**

## Constructors

### constructor

• **new UserPaginator**(`fetchPage`): [`UserPaginator`](/xdks/typescript/reference/classes/UserPaginator)

Creates a new paginator instance

#### Parameters

| Name        | Type                                                                                                                       | Description                                                   |
| :---------- | :------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
| `fetchPage` | (`token?`: `string`) => `Promise`\<[`PaginatedResponse`](/xdks/typescript/reference/interfaces/PaginatedResponse)\<`any`>> | Function that fetches a page of data given a pagination token |

#### Returns

[`UserPaginator`](/xdks/typescript/reference/classes/UserPaginator)

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[constructor](/xdks/typescript/reference/classes/Paginator#constructor)

#### Defined in

[paginator.ts:90](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L90)

## Accessors

### items

• `get` **items**(): `T`\[]

Get all fetched items

#### Returns

`T`\[]

#### Inherited from

Paginator.items

#### Defined in

[paginator.ts:97](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L97)

***

### meta

• `get` **meta**(): `any`

Get current pagination metadata

#### Returns

`any`

#### Inherited from

Paginator.meta

#### Defined in

[paginator.ts:104](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L104)

***

### includes

• `get` **includes**(): `undefined` | `Record`\<`string`, `any`>

Get current includes data

#### Returns

`undefined` | `Record`\<`string`, `any`>

#### Inherited from

Paginator.includes

#### Defined in

[paginator.ts:111](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L111)

***

### errors

• `get` **errors**(): `undefined` | `any`\[]

Get current errors

#### Returns

`undefined` | `any`\[]

#### Inherited from

Paginator.errors

#### Defined in

[paginator.ts:118](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L118)

***

### done

• `get` **done**(): `boolean`

Check if pagination is done

#### Returns

`boolean`

#### Inherited from

Paginator.done

#### Defined in

[paginator.ts:125](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L125)

***

### rateLimited

• `get` **rateLimited**(): `boolean`

Check if rate limit was hit

#### Returns

`boolean`

#### Inherited from

Paginator.rateLimited

#### Defined in

[paginator.ts:132](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L132)

***

### users

• `get` **users**(): `any`\[]

#### Returns

`any`\[]

#### Defined in

[paginator.ts:351](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L351)

## Methods

### fetchNext

▸ **fetchNext**(): `Promise`\<`void`>

Fetch the next page and add items to current instance

This method fetches the next page of data and appends the items to the
current paginator instance. It updates the pagination state and metadata.

#### Returns

`Promise`\<`void`>

**`Example`**

```typescript theme={null}
const followers = await client.users.getFollowers('783214');
await followers.fetchNext(); // Fetch first page
console.log(followers.items.length); // Number of followers

if (!followers.done) {
  await followers.fetchNext(); // Fetch second page
  console.log(followers.items.length); // Total followers across pages
}
```

**`Throws`**

When the API request fails

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[fetchNext](/xdks/typescript/reference/classes/Paginator#fetchnext)

#### Defined in

[paginator.ts:156](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L156)

***

### next

▸ **next**(): `Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>>

Get next page as a new instance

This method creates a new paginator instance that starts from the next page,
without affecting the current paginator's state.

#### Returns

`Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>>

New paginator instance for the next page

**`Example`**

```typescript theme={null}
const followers = await client.users.getFollowers('783214');
await followers.fetchNext(); // Fetch first page

if (!followers.done) {
  const nextPage = await followers.next(); // Get next page as new instance
  console.log(followers.items.length); // Still first page
  console.log(nextPage.items.length); // Second page
}
```

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[next](/xdks/typescript/reference/classes/Paginator#next)

#### Defined in

[paginator.ts:211](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L211)

***

### fetchPrevious

▸ **fetchPrevious**(): `Promise`\<`void`>

Fetch previous page (if supported)

#### Returns

`Promise`\<`void`>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[fetchPrevious](/xdks/typescript/reference/classes/Paginator#fetchprevious)

#### Defined in

[paginator.ts:225](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L225)

***

### previous

▸ **previous**(): `Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>>

Get previous page as a new instance

#### Returns

`Promise`\<[`Paginator`](/xdks/typescript/reference/classes/Paginator)\<`any`>>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[previous](/xdks/typescript/reference/classes/Paginator#previous)

#### Defined in

[paginator.ts:260](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L260)

***

### fetchLast

▸ **fetchLast**(`count`): `Promise`\<`void`>

Fetch up to a specified number of additional items

#### Parameters

| Name    | Type     |
| :------ | :------- |
| `count` | `number` |

#### Returns

`Promise`\<`void`>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[fetchLast](/xdks/typescript/reference/classes/Paginator#fetchlast)

#### Defined in

[paginator.ts:274](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L274)

***

### reset

▸ **reset**(): `void`

Reset paginator to initial state

#### Returns

`void`

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[reset](/xdks/typescript/reference/classes/Paginator#reset)

#### Defined in

[paginator.ts:288](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L288)

***

### \[iterator]

▸ **\[iterator]**(): `Iterator`\<`any`, `any`, `undefined`>

Iterator for all fetched items

#### Returns

`Iterator`\<`any`, `any`, `undefined`>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[\[iterator\]](/xdks/typescript/reference/classes/Paginator#iterator)

#### Defined in

[paginator.ts:303](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L303)

***

### \[asyncIterator]

▸ **\[asyncIterator]**(): `AsyncIterator`\<`any`, `any`, `undefined`>

Async iterator that fetches pages automatically

#### Returns

`AsyncIterator`\<`any`, `any`, `undefined`>

#### Inherited from

[Paginator](/xdks/typescript/reference/classes/Paginator).[\[asyncIterator\]](/xdks/typescript/reference/classes/Paginator#asynciterator)

#### Defined in

[paginator.ts:312](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/paginator.ts#L312)


# UsersClient
Source: https://docs.x.com/xdks/typescript/reference/classes/UsersClient

Reference for the UsersClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 users endpoints.

Client for users operations

This client provides methods for interacting with the users endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all users related operations.

## Constructors

### constructor

• **new UsersClient**(`client`): [`UsersClient`](/xdks/typescript/reference/classes/UsersClient)

Creates a new users client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`UsersClient`](/xdks/typescript/reference/classes/UsersClient)

#### Defined in

[users/client.ts:1234](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L1234)

## Methods

### getByUsernames

▸ **getByUsernames**(`usernames`, `options`): `Promise`\<`Response`>

Get Users by usernames
Retrieves details of multiple Users by their usernames.

#### Parameters

| Name        | Type                                                                  | Description                           |
| :---------- | :-------------------------------------------------------------------- | :------------------------------------ |
| `usernames` | `any`\[]                                                              | A list of usernames, comma-separated. |
| `options`   | `GetByUsernamesOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                     |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:1279](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L1279)

▸ **getByUsernames**(`usernames`, `options?`): `Promise`\<[`Get2UsersByResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersByResponse)>

#### Parameters

| Name        | Type                    |
| :---------- | :---------------------- |
| `usernames` | `any`\[]                |
| `options?`  | `GetByUsernamesOptions` |

#### Returns

`Promise`\<[`Get2UsersByResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersByResponse)>

#### Defined in

[users/client.ts:1292](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L1292)

***

### getRepostsOfMe

▸ **getRepostsOfMe**(`options`): `Promise`\<`Response`>

Get Reposts of me
Retrieves a list of Posts that repost content from the authenticated user.

#### Parameters

| Name      | Type                                                                  |
| :-------- | :-------------------------------------------------------------------- |
| `options` | `GetRepostsOfMeOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:1471](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L1471)

▸ **getRepostsOfMe**(`options?`): `Promise`\<[`Get2UsersRepostsOfMeResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersRepostsOfMeResponse)>

#### Parameters

| Name       | Type                    |
| :--------- | :---------------------- |
| `options?` | `GetRepostsOfMeOptions` |

#### Returns

`Promise`\<[`Get2UsersRepostsOfMeResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersRepostsOfMeResponse)>

#### Defined in

[users/client.ts:1480](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L1480)

***

### unlikePost

▸ **unlikePost**(`id`, `tweetId`, `options`): `Promise`\<`Response`>

Unlike Post
Causes the authenticated user to Unlike a specific Post by its ID.

#### Parameters

| Name                         | Type     | Description                                                                    |
| :--------------------------- | :------- | :----------------------------------------------------------------------------- |
| `id`                         | `string` | The ID of the authenticated source User that is requesting to unlike the Post. |
| `tweetId`                    | `string` | The ID of the Post that the User is requesting to unlike.                      |
| `options`                    | `Object` | -                                                                              |
| `options.requestOptions`     | `Object` | -                                                                              |
| `options.requestOptions.raw` | `true`   | -                                                                              |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:1741](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L1741)

▸ **unlikePost**(`id`, `tweetId`): `Promise`\<[`UsersLikesDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersLikesDeleteResponse)>

#### Parameters

| Name      | Type     |
| :-------- | :------- |
| `id`      | `string` |
| `tweetId` | `string` |

#### Returns

`Promise`\<[`UsersLikesDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersLikesDeleteResponse)>

#### Defined in

[users/client.ts:1758](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L1758)

***

### getBookmarks

▸ **getBookmarks**(`id`, `options`): `Promise`\<`Response`>

Get Bookmarks
Retrieves a list of Posts bookmarked by the authenticated user.

#### Parameters

| Name      | Type                                                                | Description                                                         |
| :-------- | :------------------------------------------------------------------ | :------------------------------------------------------------------ |
| `id`      | `string`                                                            | The ID of the authenticated source User for whom to return results. |
| `options` | `GetBookmarksOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:1861](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L1861)

▸ **getBookmarks**(`id`, `options?`): `Promise`\<[`Get2UsersIdBookmarksResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBookmarksResponse)>

#### Parameters

| Name       | Type                  |
| :--------- | :-------------------- |
| `id`       | `string`              |
| `options?` | `GetBookmarksOptions` |

#### Returns

`Promise`\<[`Get2UsersIdBookmarksResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBookmarksResponse)>

#### Defined in

[users/client.ts:1874](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L1874)

***

### createBookmark

▸ **createBookmark**(`id`, `body`, `options`): `Promise`\<`Response`>

Create Bookmark
Adds a post to the authenticated user’s bookmarks.

#### Parameters

| Name                         | Type                                                                                     | Description                                                        |
| :--------------------------- | :--------------------------------------------------------------------------------------- | :----------------------------------------------------------------- |
| `id`                         | `string`                                                                                 | The ID of the authenticated source User for whom to add bookmarks. |
| `body`                       | [`BookmarkAddRequest`](/xdks/typescript/reference/interfaces/Schemas.BookmarkAddRequest) | Request body                                                       |
| `options`                    | `Object`                                                                                 | -                                                                  |
| `options.requestOptions`     | `Object`                                                                                 | -                                                                  |
| `options.requestOptions.raw` | `true`                                                                                   | -                                                                  |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:2139](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L2139)

▸ **createBookmark**(`id`, `body`): `Promise`\<[`BookmarkMutationResponse`](/xdks/typescript/reference/interfaces/Schemas.BookmarkMutationResponse)>

#### Parameters

| Name   | Type                                                                                     |
| :----- | :--------------------------------------------------------------------------------------- |
| `id`   | `string`                                                                                 |
| `body` | [`BookmarkAddRequest`](/xdks/typescript/reference/interfaces/Schemas.BookmarkAddRequest) |

#### Returns

`Promise`\<[`BookmarkMutationResponse`](/xdks/typescript/reference/interfaces/Schemas.BookmarkMutationResponse)>

#### Defined in

[users/client.ts:2154](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L2154)

***

### getFollowers

▸ **getFollowers**(`id`, `options`): `Promise`\<`Response`>

Get followers
Retrieves a list of Users who follow a specific User by their ID.

#### Parameters

| Name      | Type                                                                | Description                   |
| :-------- | :------------------------------------------------------------------ | :---------------------------- |
| `id`      | `string`                                                            | The ID of the User to lookup. |
| `options` | `GetFollowersOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:2245](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L2245)

▸ **getFollowers**(`id`, `options?`): `Promise`\<[`Get2UsersIdFollowersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowersResponse)>

#### Parameters

| Name       | Type                  |
| :--------- | :-------------------- |
| `id`       | `string`              |
| `options?` | `GetFollowersOptions` |

#### Returns

`Promise`\<[`Get2UsersIdFollowersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowersResponse)>

#### Defined in

[users/client.ts:2258](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L2258)

***

### unpinList

▸ **unpinList**(`id`, `listId`, `options`): `Promise`\<`Response`>

Unpin List
Causes the authenticated user to unpin a specific List by its ID.

#### Parameters

| Name                         | Type     | Description                                                         |
| :--------------------------- | :------- | :------------------------------------------------------------------ |
| `id`                         | `string` | The ID of the authenticated source User for whom to return results. |
| `listId`                     | `string` | The ID of the List to unpin.                                        |
| `options`                    | `Object` | -                                                                   |
| `options.requestOptions`     | `Object` | -                                                                   |
| `options.requestOptions.raw` | `true`   | -                                                                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:2474](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L2474)

▸ **unpinList**(`id`, `listId`): `Promise`\<[`ListUnpinResponse`](/xdks/typescript/reference/interfaces/Schemas.ListUnpinResponse)>

#### Parameters

| Name     | Type     |
| :------- | :------- |
| `id`     | `string` |
| `listId` | `string` |

#### Returns

`Promise`\<[`ListUnpinResponse`](/xdks/typescript/reference/interfaces/Schemas.ListUnpinResponse)>

#### Defined in

[users/client.ts:2491](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L2491)

***

### getById

▸ **getById**(`id`, `options`): `Promise`\<`Response`>

Get User by ID
Retrieves details of a specific User by their ID.

#### Parameters

| Name      | Type                                                           | Description                   |
| :-------- | :------------------------------------------------------------- | :---------------------------- |
| `id`      | `string`                                                       | The ID of the User to lookup. |
| `options` | `GetByIdOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:2594](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L2594)

▸ **getById**(`id`, `options?`): `Promise`\<[`Get2UsersIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdResponse)>

#### Parameters

| Name       | Type             |
| :--------- | :--------------- |
| `id`       | `string`         |
| `options?` | `GetByIdOptions` |

#### Returns

`Promise`\<[`Get2UsersIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdResponse)>

#### Defined in

[users/client.ts:2607](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L2607)

***

### getMentions

▸ **getMentions**(`id`, `options`): `Promise`\<`Response`>

Get mentions
Retrieves a list of Posts that mention a specific User by their ID.

#### Parameters

| Name      | Type                                                               | Description                   |
| :-------- | :----------------------------------------------------------------- | :---------------------------- |
| `id`      | `string`                                                           | The ID of the User to lookup. |
| `options` | `GetMentionsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:2781](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L2781)

▸ **getMentions**(`id`, `options?`): `Promise`\<[`Get2UsersIdMentionsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMentionsResponse)>

#### Parameters

| Name       | Type                 |
| :--------- | :------------------- |
| `id`       | `string`             |
| `options?` | `GetMentionsOptions` |

#### Returns

`Promise`\<[`Get2UsersIdMentionsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMentionsResponse)>

#### Defined in

[users/client.ts:2794](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L2794)

***

### unrepostPost

▸ **unrepostPost**(`id`, `sourceTweetId`, `options`): `Promise`\<`Response`>

Unrepost Post
Causes the authenticated user to unrepost a specific Post by its ID.

#### Parameters

| Name                         | Type     | Description                                                                    |
| :--------------------------- | :------- | :----------------------------------------------------------------------------- |
| `id`                         | `string` | The ID of the authenticated source User that is requesting to repost the Post. |
| `sourceTweetId`              | `string` | The ID of the Post that the User is requesting to unretweet.                   |
| `options`                    | `Object` | -                                                                              |
| `options.requestOptions`     | `Object` | -                                                                              |
| `options.requestOptions.raw` | `true`   | -                                                                              |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:3149](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L3149)

▸ **unrepostPost**(`id`, `sourceTweetId`): `Promise`\<[`UsersRetweetsDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsDeleteResponse)>

#### Parameters

| Name            | Type     |
| :-------------- | :------- |
| `id`            | `string` |
| `sourceTweetId` | `string` |

#### Returns

`Promise`\<[`UsersRetweetsDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsDeleteResponse)>

#### Defined in

[users/client.ts:3166](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L3166)

***

### deleteBookmark

▸ **deleteBookmark**(`id`, `tweetId`, `options`): `Promise`\<`Response`>

Delete Bookmark
Removes a Post from the authenticated user’s Bookmarks by its ID.

#### Parameters

| Name                         | Type     | Description                                                              |
| :--------------------------- | :------- | :----------------------------------------------------------------------- |
| `id`                         | `string` | The ID of the authenticated source User whose bookmark is to be removed. |
| `tweetId`                    | `string` | The ID of the Post that the source User is removing from bookmarks.      |
| `options`                    | `Object` | -                                                                        |
| `options.requestOptions`     | `Object` | -                                                                        |
| `options.requestOptions.raw` | `true`   | -                                                                        |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:3273](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L3273)

▸ **deleteBookmark**(`id`, `tweetId`): `Promise`\<[`BookmarkMutationResponse`](/xdks/typescript/reference/interfaces/Schemas.BookmarkMutationResponse)>

#### Parameters

| Name      | Type     |
| :-------- | :------- |
| `id`      | `string` |
| `tweetId` | `string` |

#### Returns

`Promise`\<[`BookmarkMutationResponse`](/xdks/typescript/reference/interfaces/Schemas.BookmarkMutationResponse)>

#### Defined in

[users/client.ts:3290](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L3290)

***

### unfollowList

▸ **unfollowList**(`id`, `listId`, `options`): `Promise`\<`Response`>

Unfollow List
Causes the authenticated user to unfollow a specific List by its ID.

#### Parameters

| Name                         | Type     | Description                                                          |
| :--------------------------- | :------- | :------------------------------------------------------------------- |
| `id`                         | `string` | The ID of the authenticated source User that will unfollow the List. |
| `listId`                     | `string` | The ID of the List to unfollow.                                      |
| `options`                    | `Object` | -                                                                    |
| `options.requestOptions`     | `Object` | -                                                                    |
| `options.requestOptions.raw` | `true`   | -                                                                    |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:3391](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L3391)

▸ **unfollowList**(`id`, `listId`): `Promise`\<[`ListFollowedResponse`](/xdks/typescript/reference/interfaces/Schemas.ListFollowedResponse)>

#### Parameters

| Name     | Type     |
| :------- | :------- |
| `id`     | `string` |
| `listId` | `string` |

#### Returns

`Promise`\<[`ListFollowedResponse`](/xdks/typescript/reference/interfaces/Schemas.ListFollowedResponse)>

#### Defined in

[users/client.ts:3408](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L3408)

***

### unmuteUser

▸ **unmuteUser**(`sourceUserId`, `targetUserId`, `options`): `Promise`\<`Response`>

Unmute User
Causes the authenticated user to unmute a specific user by their ID.

#### Parameters

| Name                         | Type     | Description                                                                           |
| :--------------------------- | :------- | :------------------------------------------------------------------------------------ |
| `sourceUserId`               | `string` | The ID of the authenticated source User that is requesting to unmute the target User. |
| `targetUserId`               | `string` | The ID of the User that the source User is requesting to unmute.                      |
| `options`                    | `Object` | -                                                                                     |
| `options.requestOptions`     | `Object` | -                                                                                     |
| `options.requestOptions.raw` | `true`   | -                                                                                     |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:3515](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L3515)

▸ **unmuteUser**(`sourceUserId`, `targetUserId`): `Promise`\<[`MuteUserMutationResponse`](/xdks/typescript/reference/interfaces/Schemas.MuteUserMutationResponse)>

#### Parameters

| Name           | Type     |
| :------------- | :------- |
| `sourceUserId` | `string` |
| `targetUserId` | `string` |

#### Returns

`Promise`\<[`MuteUserMutationResponse`](/xdks/typescript/reference/interfaces/Schemas.MuteUserMutationResponse)>

#### Defined in

[users/client.ts:3532](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L3532)

***

### getMe

▸ **getMe**(`options`): `Promise`\<`Response`>

Get my User
Retrieves details of the authenticated user.

#### Parameters

| Name      | Type                                                         |
| :-------- | :----------------------------------------------------------- |
| `options` | `GetMeOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:3631](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L3631)

▸ **getMe**(`options?`): `Promise`\<[`Get2UsersMeResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersMeResponse)>

#### Parameters

| Name       | Type           |
| :--------- | :------------- |
| `options?` | `GetMeOptions` |

#### Returns

`Promise`\<[`Get2UsersMeResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersMeResponse)>

#### Defined in

[users/client.ts:3640](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L3640)

***

### getMuting

▸ **getMuting**(`id`, `options`): `Promise`\<`Response`>

Get muting
Retrieves a list of Users muted by the authenticated user.

#### Parameters

| Name      | Type                                                             | Description                                                         |
| :-------- | :--------------------------------------------------------------- | :------------------------------------------------------------------ |
| `id`      | `string`                                                         | The ID of the authenticated source User for whom to return results. |
| `options` | `GetMutingOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:3796](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L3796)

▸ **getMuting**(`id`, `options?`): `Promise`\<[`Get2UsersIdMutingResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMutingResponse)>

#### Parameters

| Name       | Type               |
| :--------- | :----------------- |
| `id`       | `string`           |
| `options?` | `GetMutingOptions` |

#### Returns

`Promise`\<[`Get2UsersIdMutingResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMutingResponse)>

#### Defined in

[users/client.ts:3809](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L3809)

***

### muteUser

▸ **muteUser**(`id`, `options`): `Promise`\<`Response`>

Mute User
Causes the authenticated user to mute a specific User by their ID.

#### Parameters

| Name      | Type                                                            | Description                                                                         |
| :-------- | :-------------------------------------------------------------- | :---------------------------------------------------------------------------------- |
| `id`      | `string`                                                        | The ID of the authenticated source User that is requesting to mute the target User. |
| `options` | `MuteUserOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:4015](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L4015)

▸ **muteUser**(`id`, `options?`): `Promise`\<[`MuteUserMutationResponse`](/xdks/typescript/reference/interfaces/Schemas.MuteUserMutationResponse)>

#### Parameters

| Name       | Type              |
| :--------- | :---------------- |
| `id`       | `string`          |
| `options?` | `MuteUserOptions` |

#### Returns

`Promise`\<[`MuteUserMutationResponse`](/xdks/typescript/reference/interfaces/Schemas.MuteUserMutationResponse)>

#### Defined in

[users/client.ts:4028](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L4028)

***

### search

▸ **search**(`query`, `options`): `Promise`\<`Response`>

Search Users
Retrieves a list of Users matching a search query.

#### Parameters

| Name      | Type                                                          | Description                                        |
| :-------- | :------------------------------------------------------------ | :------------------------------------------------- |
| `query`   | `string`                                                      | TThe the query string by which to query for users. |
| `options` | `SearchOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                  |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:4136](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L4136)

▸ **search**(`query`, `options?`): `Promise`\<[`Get2UsersSearchResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersSearchResponse)>

#### Parameters

| Name       | Type            |
| :--------- | :-------------- |
| `query`    | `string`        |
| `options?` | `SearchOptions` |

#### Returns

`Promise`\<[`Get2UsersSearchResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersSearchResponse)>

#### Defined in

[users/client.ts:4149](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L4149)

***

### getBlocking

▸ **getBlocking**(`id`, `options`): `Promise`\<`Response`>

Get blocking
Retrieves a list of Users blocked by the specified User ID.

#### Parameters

| Name      | Type                                                               | Description                                                         |
| :-------- | :----------------------------------------------------------------- | :------------------------------------------------------------------ |
| `id`      | `string`                                                           | The ID of the authenticated source User for whom to return results. |
| `options` | `GetBlockingOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:4362](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L4362)

▸ **getBlocking**(`id`, `options?`): `Promise`\<[`Get2UsersIdBlockingResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBlockingResponse)>

#### Parameters

| Name       | Type                 |
| :--------- | :------------------- |
| `id`       | `string`             |
| `options?` | `GetBlockingOptions` |

#### Returns

`Promise`\<[`Get2UsersIdBlockingResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBlockingResponse)>

#### Defined in

[users/client.ts:4375](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L4375)

***

### getByIds

▸ **getByIds**(`ids`, `options`): `Promise`\<`Response`>

Get Users by IDs
Retrieves details of multiple Users by their IDs.

#### Parameters

| Name      | Type                                                            | Description                                                         |
| :-------- | :-------------------------------------------------------------- | :------------------------------------------------------------------ |
| `ids`     | `any`\[]                                                        | A list of User IDs, comma-separated. You can specify up to 100 IDs. |
| `options` | `GetByIdsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:4581](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L4581)

▸ **getByIds**(`ids`, `options?`): `Promise`\<[`Get2UsersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersResponse)>

#### Parameters

| Name       | Type              |
| :--------- | :---------------- |
| `ids`      | `any`\[]          |
| `options?` | `GetByIdsOptions` |

#### Returns

`Promise`\<[`Get2UsersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersResponse)>

#### Defined in

[users/client.ts:4594](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L4594)

***

### getFollowing

▸ **getFollowing**(`id`, `options`): `Promise`\<`Response`>

Get following
Retrieves a list of Users followed by a specific User by their ID.

#### Parameters

| Name      | Type                                                                | Description                   |
| :-------- | :------------------------------------------------------------------ | :---------------------------- |
| `id`      | `string`                                                            | The ID of the User to lookup. |
| `options` | `GetFollowingOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:4777](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L4777)

▸ **getFollowing**(`id`, `options?`): `Promise`\<[`Get2UsersIdFollowingResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowingResponse)>

#### Parameters

| Name       | Type                  |
| :--------- | :-------------------- |
| `id`       | `string`              |
| `options?` | `GetFollowingOptions` |

#### Returns

`Promise`\<[`Get2UsersIdFollowingResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowingResponse)>

#### Defined in

[users/client.ts:4790](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L4790)

***

### followUser

▸ **followUser**(`id`, `options`): `Promise`\<`Response`>

Follow User
Causes the authenticated user to follow a specific user by their ID.

#### Parameters

| Name      | Type                                                              | Description                                                                           |
| :-------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------ |
| `id`      | `string`                                                          | The ID of the authenticated source User that is requesting to follow the target User. |
| `options` | `FollowUserOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                     |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:5002](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L5002)

▸ **followUser**(`id`, `options?`): `Promise`\<[`UsersFollowingCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateResponse)>

#### Parameters

| Name       | Type                |
| :--------- | :------------------ |
| `id`       | `string`            |
| `options?` | `FollowUserOptions` |

#### Returns

`Promise`\<[`UsersFollowingCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateResponse)>

#### Defined in

[users/client.ts:5015](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L5015)

***

### likePost

▸ **likePost**(`id`, `options`): `Promise`\<`Response`>

Like Post
Causes the authenticated user to Like a specific Post by its ID.

#### Parameters

| Name      | Type                                                            | Description                                                                  |
| :-------- | :-------------------------------------------------------------- | :--------------------------------------------------------------------------- |
| `id`      | `string`                                                        | The ID of the authenticated source User that is requesting to like the Post. |
| `options` | `LikePostOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                            |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:5123](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L5123)

▸ **likePost**(`id`, `options?`): `Promise`\<[`UsersLikesCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateResponse)>

#### Parameters

| Name       | Type              |
| :--------- | :---------------- |
| `id`       | `string`          |
| `options?` | `LikePostOptions` |

#### Returns

`Promise`\<[`UsersLikesCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateResponse)>

#### Defined in

[users/client.ts:5136](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L5136)

***

### getLikedPosts

▸ **getLikedPosts**(`id`, `options`): `Promise`\<`Response`>

Get liked Posts
Retrieves a list of Posts liked by a specific User by their ID.

#### Parameters

| Name      | Type                                                                 | Description                   |
| :-------- | :------------------------------------------------------------------- | :---------------------------- |
| `id`      | `string`                                                             | The ID of the User to lookup. |
| `options` | `GetLikedPostsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:5244](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L5244)

▸ **getLikedPosts**(`id`, `options?`): `Promise`\<[`Get2UsersIdLikedTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdLikedTweetsResponse)>

#### Parameters

| Name       | Type                   |
| :--------- | :--------------------- |
| `id`       | `string`               |
| `options?` | `GetLikedPostsOptions` |

#### Returns

`Promise`\<[`Get2UsersIdLikedTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdLikedTweetsResponse)>

#### Defined in

[users/client.ts:5257](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L5257)

***

### getPosts

▸ **getPosts**(`id`, `options`): `Promise`\<`Response`>

Get Posts
Retrieves a list of posts authored by a specific User by their ID.

#### Parameters

| Name      | Type                                                            | Description                   |
| :-------- | :-------------------------------------------------------------- | :---------------------------- |
| `id`      | `string`                                                        | The ID of the User to lookup. |
| `options` | `GetPostsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:5526](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L5526)

▸ **getPosts**(`id`, `options?`): `Promise`\<[`Get2UsersIdTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTweetsResponse)>

#### Parameters

| Name       | Type              |
| :--------- | :---------------- |
| `id`       | `string`          |
| `options?` | `GetPostsOptions` |

#### Returns

`Promise`\<[`Get2UsersIdTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTweetsResponse)>

#### Defined in

[users/client.ts:5539](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L5539)

***

### blockDms

▸ **blockDms**(`id`, `options`): `Promise`\<`Response`>

Block DMs
Blocks direct messages to or from a specific User by their ID for the authenticated user.

#### Parameters

| Name                         | Type     | Description                                                                        |
| :--------------------------- | :------- | :--------------------------------------------------------------------------------- |
| `id`                         | `string` | The ID of the target User that the authenticated user requesting to block dms for. |
| `options`                    | `Object` | -                                                                                  |
| `options.requestOptions`     | `Object` | -                                                                                  |
| `options.requestOptions.raw` | `true`   | -                                                                                  |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:5909](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L5909)

▸ **blockDms**(`id`): `Promise`\<[`UsersDMBlockCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersDMBlockCreateResponse)>

#### Parameters

| Name | Type     |
| :--- | :------- |
| `id` | `string` |

#### Returns

`Promise`\<[`UsersDMBlockCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersDMBlockCreateResponse)>

#### Defined in

[users/client.ts:5922](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L5922)

***

### getListMemberships

▸ **getListMemberships**(`id`, `options`): `Promise`\<`Response`>

Get List memberships
Retrieves a list of Lists that a specific User is a member of by their ID.

#### Parameters

| Name      | Type                                                                      | Description                   |
| :-------- | :------------------------------------------------------------------------ | :---------------------------- |
| `id`      | `string`                                                                  | The ID of the User to lookup. |
| `options` | `GetListMembershipsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:6013](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L6013)

▸ **getListMemberships**(`id`, `options?`): `Promise`\<[`Get2UsersIdListMembershipsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdListMembershipsResponse)>

#### Parameters

| Name       | Type                        |
| :--------- | :-------------------------- |
| `id`       | `string`                    |
| `options?` | `GetListMembershipsOptions` |

#### Returns

`Promise`\<[`Get2UsersIdListMembershipsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdListMembershipsResponse)>

#### Defined in

[users/client.ts:6026](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L6026)

***

### getPinnedLists

▸ **getPinnedLists**(`id`, `options`): `Promise`\<`Response`>

Get pinned Lists
Retrieves a list of Lists pinned by the authenticated user.

#### Parameters

| Name      | Type                                                                  | Description                                                         |
| :-------- | :-------------------------------------------------------------------- | :------------------------------------------------------------------ |
| `id`      | `string`                                                              | The ID of the authenticated source User for whom to return results. |
| `options` | `GetPinnedListsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:6238](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L6238)

▸ **getPinnedLists**(`id`, `options?`): `Promise`\<[`Get2UsersIdPinnedListsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdPinnedListsResponse)>

#### Parameters

| Name       | Type                    |
| :--------- | :---------------------- |
| `id`       | `string`                |
| `options?` | `GetPinnedListsOptions` |

#### Returns

`Promise`\<[`Get2UsersIdPinnedListsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdPinnedListsResponse)>

#### Defined in

[users/client.ts:6251](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L6251)

***

### pinList

▸ **pinList**(`id`, `body`, `options`): `Promise`\<`Response`>

Pin List
Causes the authenticated user to pin a specific List by its ID.

#### Parameters

| Name                         | Type                                                                                   | Description                                                     |
| :--------------------------- | :------------------------------------------------------------------------------------- | :-------------------------------------------------------------- |
| `id`                         | `string`                                                                               | The ID of the authenticated source User that will pin the List. |
| `body`                       | [`ListPinnedRequest`](/xdks/typescript/reference/interfaces/Schemas.ListPinnedRequest) | Request body                                                    |
| `options`                    | `Object`                                                                               | -                                                               |
| `options.requestOptions`     | `Object`                                                                               | -                                                               |
| `options.requestOptions.raw` | `true`                                                                                 | -                                                               |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:6421](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L6421)

▸ **pinList**(`id`, `body`): `Promise`\<[`ListPinnedResponse`](/xdks/typescript/reference/interfaces/Schemas.ListPinnedResponse)>

#### Parameters

| Name   | Type                                                                                   |
| :----- | :------------------------------------------------------------------------------------- |
| `id`   | `string`                                                                               |
| `body` | [`ListPinnedRequest`](/xdks/typescript/reference/interfaces/Schemas.ListPinnedRequest) |

#### Returns

`Promise`\<[`ListPinnedResponse`](/xdks/typescript/reference/interfaces/Schemas.ListPinnedResponse)>

#### Defined in

[users/client.ts:6436](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L6436)

***

### getByUsername

▸ **getByUsername**(`username`, `options`): `Promise`\<`Response`>

Get User by username
Retrieves details of a specific User by their username.

#### Parameters

| Name       | Type                                                                 | Description |
| :--------- | :------------------------------------------------------------------- | :---------- |
| `username` | `string`                                                             | A username. |
| `options`  | `GetByUsernameOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -           |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:6533](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L6533)

▸ **getByUsername**(`username`, `options?`): `Promise`\<[`Get2UsersByUsernameUsernameResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersByUsernameUsernameResponse)>

#### Parameters

| Name       | Type                   |
| :--------- | :--------------------- |
| `username` | `string`               |
| `options?` | `GetByUsernameOptions` |

#### Returns

`Promise`\<[`Get2UsersByUsernameUsernameResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersByUsernameUsernameResponse)>

#### Defined in

[users/client.ts:6546](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L6546)

***

### unfollowUser

▸ **unfollowUser**(`sourceUserId`, `targetUserId`, `options`): `Promise`\<`Response`>

Unfollow User
Causes the authenticated user to unfollow a specific user by their ID.

#### Parameters

| Name                         | Type     | Description                                                                             |
| :--------------------------- | :------- | :-------------------------------------------------------------------------------------- |
| `sourceUserId`               | `string` | The ID of the authenticated source User that is requesting to unfollow the target User. |
| `targetUserId`               | `string` | The ID of the User that the source User is requesting to unfollow.                      |
| `options`                    | `Object` | -                                                                                       |
| `options.requestOptions`     | `Object` | -                                                                                       |
| `options.requestOptions.raw` | `true`   | -                                                                                       |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:6724](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L6724)

▸ **unfollowUser**(`sourceUserId`, `targetUserId`): `Promise`\<[`UsersFollowingDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingDeleteResponse)>

#### Parameters

| Name           | Type     |
| :------------- | :------- |
| `sourceUserId` | `string` |
| `targetUserId` | `string` |

#### Returns

`Promise`\<[`UsersFollowingDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingDeleteResponse)>

#### Defined in

[users/client.ts:6741](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L6741)

***

### getTimeline

▸ **getTimeline**(`id`, `options`): `Promise`\<`Response`>

Get Timeline
Retrieves a reverse chronological list of Posts in the authenticated User’s Timeline.

#### Parameters

| Name      | Type                                                               | Description                                                                              |
| :-------- | :----------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
| `id`      | `string`                                                           | The ID of the authenticated source User to list Reverse Chronological Timeline Posts of. |
| `options` | `GetTimelineOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                                        |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:6844](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L6844)

▸ **getTimeline**(`id`, `options?`): `Promise`\<[`Get2UsersIdTimelinesReverseChronologicalResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTimelinesReverseChronologicalResponse)>

#### Parameters

| Name       | Type                 |
| :--------- | :------------------- |
| `id`       | `string`             |
| `options?` | `GetTimelineOptions` |

#### Returns

`Promise`\<[`Get2UsersIdTimelinesReverseChronologicalResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTimelinesReverseChronologicalResponse)>

#### Defined in

[users/client.ts:6857](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L6857)

***

### getFollowedLists

▸ **getFollowedLists**(`id`, `options`): `Promise`\<`Response`>

Get followed Lists
Retrieves a list of Lists followed by a specific User by their ID.

#### Parameters

| Name      | Type                                                                    | Description                   |
| :-------- | :---------------------------------------------------------------------- | :---------------------------- |
| `id`      | `string`                                                                | The ID of the User to lookup. |
| `options` | `GetFollowedListsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:7221](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L7221)

▸ **getFollowedLists**(`id`, `options?`): `Promise`\<[`Get2UsersIdFollowedListsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowedListsResponse)>

#### Parameters

| Name       | Type                      |
| :--------- | :------------------------ |
| `id`       | `string`                  |
| `options?` | `GetFollowedListsOptions` |

#### Returns

`Promise`\<[`Get2UsersIdFollowedListsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowedListsResponse)>

#### Defined in

[users/client.ts:7234](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L7234)

***

### followList

▸ **followList**(`id`, `options`): `Promise`\<`Response`>

Follow List
Causes the authenticated user to follow a specific List by its ID.

#### Parameters

| Name      | Type                                                              | Description                                                        |
| :-------- | :---------------------------------------------------------------- | :----------------------------------------------------------------- |
| `id`      | `string`                                                          | The ID of the authenticated source User that will follow the List. |
| `options` | `FollowListOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                  |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:7446](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L7446)

▸ **followList**(`id`, `options?`): `Promise`\<[`ListFollowedResponse`](/xdks/typescript/reference/interfaces/Schemas.ListFollowedResponse)>

#### Parameters

| Name       | Type                |
| :--------- | :------------------ |
| `id`       | `string`            |
| `options?` | `FollowListOptions` |

#### Returns

`Promise`\<[`ListFollowedResponse`](/xdks/typescript/reference/interfaces/Schemas.ListFollowedResponse)>

#### Defined in

[users/client.ts:7459](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L7459)

***

### unblockDms

▸ **unblockDms**(`id`, `options`): `Promise`\<`Response`>

Unblock DMs
Unblocks direct messages to or from a specific User by their ID for the authenticated user.

#### Parameters

| Name                         | Type     | Description                                                                          |
| :--------------------------- | :------- | :----------------------------------------------------------------------------------- |
| `id`                         | `string` | The ID of the target User that the authenticated user requesting to unblock dms for. |
| `options`                    | `Object` | -                                                                                    |
| `options.requestOptions`     | `Object` | -                                                                                    |
| `options.requestOptions.raw` | `true`   | -                                                                                    |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:7567](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L7567)

▸ **unblockDms**(`id`): `Promise`\<[`UsersDMUnBlockCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersDMUnBlockCreateResponse)>

#### Parameters

| Name | Type     |
| :--- | :------- |
| `id` | `string` |

#### Returns

`Promise`\<[`UsersDMUnBlockCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersDMUnBlockCreateResponse)>

#### Defined in

[users/client.ts:7580](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L7580)

***

### repostPost

▸ **repostPost**(`id`, `options`): `Promise`\<`Response`>

Repost Post
Causes the authenticated user to repost a specific Post by its ID.

#### Parameters

| Name      | Type                                                              | Description                                                                    |
| :-------- | :---------------------------------------------------------------- | :----------------------------------------------------------------------------- |
| `id`      | `string`                                                          | The ID of the authenticated source User that is requesting to repost the Post. |
| `options` | `RepostPostOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                              |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:7671](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L7671)

▸ **repostPost**(`id`, `options?`): `Promise`\<[`UsersRetweetsCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateResponse)>

#### Parameters

| Name       | Type                |
| :--------- | :------------------ |
| `id`       | `string`            |
| `options?` | `RepostPostOptions` |

#### Returns

`Promise`\<[`UsersRetweetsCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateResponse)>

#### Defined in

[users/client.ts:7684](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L7684)

***

### getBookmarkFolders

▸ **getBookmarkFolders**(`id`, `options`): `Promise`\<`Response`>

Get Bookmark folders
Retrieves a list of Bookmark folders created by the authenticated user.

#### Parameters

| Name      | Type                                                                      | Description                                                         |
| :-------- | :------------------------------------------------------------------------ | :------------------------------------------------------------------ |
| `id`      | `string`                                                                  | The ID of the authenticated source User for whom to return results. |
| `options` | `GetBookmarkFoldersOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                                   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:7792](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L7792)

▸ **getBookmarkFolders**(`id`, `options?`): `Promise`\<[`BookmarkFoldersResponse`](/xdks/typescript/reference/interfaces/Schemas.BookmarkFoldersResponse)>

#### Parameters

| Name       | Type                        |
| :--------- | :-------------------------- |
| `id`       | `string`                    |
| `options?` | `GetBookmarkFoldersOptions` |

#### Returns

`Promise`\<[`BookmarkFoldersResponse`](/xdks/typescript/reference/interfaces/Schemas.BookmarkFoldersResponse)>

#### Defined in

[users/client.ts:7805](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L7805)

***

### getOwnedLists

▸ **getOwnedLists**(`id`, `options`): `Promise`\<`Response`>

Get owned Lists
Retrieves a list of Lists owned by a specific User by their ID.

#### Parameters

| Name      | Type                                                                 | Description                   |
| :-------- | :------------------------------------------------------------------- | :---------------------------- |
| `id`      | `string`                                                             | The ID of the User to lookup. |
| `options` | `GetOwnedListsOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                             |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:7944](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L7944)

▸ **getOwnedLists**(`id`, `options?`): `Promise`\<[`Get2UsersIdOwnedListsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdOwnedListsResponse)>

#### Parameters

| Name       | Type                   |
| :--------- | :--------------------- |
| `id`       | `string`               |
| `options?` | `GetOwnedListsOptions` |

#### Returns

`Promise`\<[`Get2UsersIdOwnedListsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdOwnedListsResponse)>

#### Defined in

[users/client.ts:7957](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L7957)

***

### getBookmarksByFolderId

▸ **getBookmarksByFolderId**(`id`, `folderId`, `options`): `Promise`\<`Response`>

Get Bookmarks by folder ID
Retrieves Posts in a specific Bookmark folder by its ID for the authenticated user.

#### Parameters

| Name                         | Type     | Description                                                                             |
| :--------------------------- | :------- | :-------------------------------------------------------------------------------------- |
| `id`                         | `string` | The ID of the authenticated source User for whom to return results.                     |
| `folderId`                   | `string` | The ID of the Bookmark Folder that the authenticated User is trying to fetch Posts for. |
| `options`                    | `Object` | -                                                                                       |
| `options.requestOptions`     | `Object` | -                                                                                       |
| `options.requestOptions.raw` | `true`   | -                                                                                       |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[users/client.ts:8173](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L8173)

▸ **getBookmarksByFolderId**(`id`, `folderId`): `Promise`\<[`BookmarkFolderPostsResponse`](/xdks/typescript/reference/interfaces/Schemas.BookmarkFolderPostsResponse)>

#### Parameters

| Name       | Type     |
| :--------- | :------- |
| `id`       | `string` |
| `folderId` | `string` |

#### Returns

`Promise`\<[`BookmarkFolderPostsResponse`](/xdks/typescript/reference/interfaces/Schemas.BookmarkFolderPostsResponse)>

#### Defined in

[users/client.ts:8190](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/client.ts#L8190)


# WebhooksClient
Source: https://docs.x.com/xdks/typescript/reference/classes/WebhooksClient

Reference for the WebhooksClient class in the X API TypeScript SDK. Methods, parameters, and return types for the X API v2 webhooks endpoints.

Client for webhooks operations

This client provides methods for interacting with the webhooks endpoints
of the X API. It handles authentication, request formatting, and response
parsing for all webhooks related operations.

## Constructors

### constructor

• **new WebhooksClient**(`client`): [`WebhooksClient`](/xdks/typescript/reference/classes/WebhooksClient)

Creates a new webhooks client instance

#### Parameters

| Name     | Type                                                  | Description                    |
| :------- | :---------------------------------------------------- | :----------------------------- |
| `client` | [`Client`](/xdks/typescript/reference/classes/Client) | The main X API client instance |

#### Returns

[`WebhooksClient`](/xdks/typescript/reference/classes/WebhooksClient)

#### Defined in

[webhooks/client.ts:162](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L162)

## Methods

### createStreamLink

▸ **createStreamLink**(`webhookId`, `options`): `Promise`\<`Response`>

Create stream link
Creates a link to deliver FilteredStream events to the given webhook.

#### Parameters

| Name        | Type                                                                    | Description                                            |
| :---------- | :---------------------------------------------------------------------- | :----------------------------------------------------- |
| `webhookId` | `string`                                                                | The webhook ID to link to your FilteredStream ruleset. |
| `options`   | `CreateStreamLinkOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } | -                                                      |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[webhooks/client.ts:207](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L207)

▸ **createStreamLink**(`webhookId`, `options?`): `Promise`\<[`WebhookLinksCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksCreateResponse)>

#### Parameters

| Name        | Type                      |
| :---------- | :------------------------ |
| `webhookId` | `string`                  |
| `options?`  | `CreateStreamLinkOptions` |

#### Returns

`Promise`\<[`WebhookLinksCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksCreateResponse)>

#### Defined in

[webhooks/client.ts:220](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L220)

***

### deleteStreamLink

▸ **deleteStreamLink**(`webhookId`, `options`): `Promise`\<`Response`>

Delete stream link
Deletes a link from FilteredStream events to the given webhook.

#### Parameters

| Name                         | Type     | Description                                            |
| :--------------------------- | :------- | :----------------------------------------------------- |
| `webhookId`                  | `string` | The webhook ID to link to your FilteredStream ruleset. |
| `options`                    | `Object` | -                                                      |
| `options.requestOptions`     | `Object` | -                                                      |
| `options.requestOptions.raw` | `true`   | -                                                      |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[webhooks/client.ts:433](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L433)

▸ **deleteStreamLink**(`webhookId`): `Promise`\<[`WebhookLinksDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksDeleteResponse)>

#### Parameters

| Name        | Type     |
| :---------- | :------- |
| `webhookId` | `string` |

#### Returns

`Promise`\<[`WebhookLinksDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksDeleteResponse)>

#### Defined in

[webhooks/client.ts:446](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L446)

***

### getStreamLinks

▸ **getStreamLinks**(`options`): `Promise`\<`Response`>

Get stream links
Get a list of webhook links associated with a filtered stream ruleset.

#### Parameters

| Name                         | Type     |
| :--------------------------- | :------- |
| `options`                    | `Object` |
| `options.requestOptions`     | `Object` |
| `options.requestOptions.raw` | `true`   |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[webhooks/client.ts:527](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L527)

▸ **getStreamLinks**(): `Promise`\<[`WebhookLinksGetResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksGetResponse)>

#### Returns

`Promise`\<[`WebhookLinksGetResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksGetResponse)>

#### Defined in

[webhooks/client.ts:536](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L536)

***

### createWebhookReplayJob

▸ **createWebhookReplayJob**(`options`): `Promise`\<`Response`>

Create replay job for webhook
Creates a replay job to retrieve events from up to the past 24 hours for all events delivered or attempted to be delivered to the webhook.

#### Parameters

| Name      | Type                                                                          |
| :-------- | :---------------------------------------------------------------------------- |
| `options` | `CreateWebhookReplayJobOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[webhooks/client.ts:605](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L605)

▸ **createWebhookReplayJob**(`options?`): `Promise`\<[`ReplayJobCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.ReplayJobCreateResponse)>

#### Parameters

| Name       | Type                            |
| :--------- | :------------------------------ |
| `options?` | `CreateWebhookReplayJobOptions` |

#### Returns

`Promise`\<[`ReplayJobCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.ReplayJobCreateResponse)>

#### Defined in

[webhooks/client.ts:614](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L614)

***

### validate

▸ **validate**(`webhookId`, `options`): `Promise`\<`Response`>

Validate webhook
Triggers a CRC check for a given webhook.

#### Parameters

| Name                         | Type     | Description                     |
| :--------------------------- | :------- | :------------------------------ |
| `webhookId`                  | `string` | The ID of the webhook to check. |
| `options`                    | `Object` | -                               |
| `options.requestOptions`     | `Object` | -                               |
| `options.requestOptions.raw` | `true`   | -                               |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[webhooks/client.ts:704](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L704)

▸ **validate**(`webhookId`): `Promise`\<[`WebhookConfigPutResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigPutResponse)>

#### Parameters

| Name        | Type     |
| :---------- | :------- |
| `webhookId` | `string` |

#### Returns

`Promise`\<[`WebhookConfigPutResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigPutResponse)>

#### Defined in

[webhooks/client.ts:717](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L717)

***

### delete

▸ **delete**(`webhookId`, `options`): `Promise`\<`Response`>

Delete webhook
Deletes an existing webhook configuration.

#### Parameters

| Name                         | Type     | Description                      |
| :--------------------------- | :------- | :------------------------------- |
| `webhookId`                  | `string` | The ID of the webhook to delete. |
| `options`                    | `Object` | -                                |
| `options.requestOptions`     | `Object` | -                                |
| `options.requestOptions.raw` | `true`   | -                                |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[webhooks/client.ts:808](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L808)

▸ **delete**(`webhookId`): `Promise`\<[`WebhookConfigDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigDeleteResponse)>

#### Parameters

| Name        | Type     |
| :---------- | :------- |
| `webhookId` | `string` |

#### Returns

`Promise`\<[`WebhookConfigDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigDeleteResponse)>

#### Defined in

[webhooks/client.ts:821](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L821)

***

### get

▸ **get**(`options`): `Promise`\<`Response`>

Get webhook
Get a list of webhook configs associated with a client app.

#### Parameters

| Name      | Type                                                       |
| :-------- | :--------------------------------------------------------- |
| `options` | `GetOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[webhooks/client.ts:908](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L908)

▸ **get**(`options?`): `Promise`\<[`Get2WebhooksResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2WebhooksResponse)>

#### Parameters

| Name       | Type         |
| :--------- | :----------- |
| `options?` | `GetOptions` |

#### Returns

`Promise`\<[`Get2WebhooksResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2WebhooksResponse)>

#### Defined in

[webhooks/client.ts:917](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L917)

***

### create

▸ **create**(`options`): `Promise`\<`Response`>

Create webhook
Creates a new webhook configuration.

#### Parameters

| Name      | Type                                                          |
| :-------- | :------------------------------------------------------------ |
| `options` | `CreateOptions` & \{ `requestOptions`: \{ `raw`: `true`  }  } |

#### Returns

`Promise`\<`Response`>

Promise resolving to the API response, or raw Response if requestOptions.raw is true

#### Defined in

[webhooks/client.ts:1023](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L1023)

▸ **create**(`options?`): `Promise`\<[`WebhookConfigCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateResponse)>

#### Parameters

| Name       | Type            |
| :--------- | :-------------- |
| `options?` | `CreateOptions` |

#### Returns

`Promise`\<[`WebhookConfigCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateResponse)>

#### Defined in

[webhooks/client.ts:1032](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/client.ts#L1032)


# ApiResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/ApiResponse

Reference for the ApiResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

Response wrapper with metadata

## Type parameters

| Name | Type  |
| :--- | :---- |
| `T`  | `any` |

## Properties

<ResponseField name="body" type="T">
  Response body
</ResponseField>

<ResponseField name="headers" type="Headers">
  Response headers
</ResponseField>

<ResponseField name="status" type="number">
  HTTP status code
</ResponseField>

<ResponseField name="statusText" type="string">
  HTTP status text
</ResponseField>

<ResponseField name="url" type="string">
  Response URL
</ResponseField>


# ClientConfig
Source: https://docs.x.com/xdks/typescript/reference/interfaces/ClientConfig

Reference for the ClientConfig TypeScript interface in the X API SDK. Configuration options for the X API client Bearer token for authentication OAuth1.

Configuration options for the X API client

## Properties

<ResponseField name="baseUrl" type="string">
  Base URL for API requests
</ResponseField>

<ResponseField name="bearerToken" type="string">
  Bearer token for authentication
</ResponseField>

<ResponseField name="accessToken" type="string">
  OAuth2 access token
</ResponseField>

<ResponseField name="oauth1" type="any">
  OAuth1 instance for authentication
</ResponseField>

<ResponseField name="headers" type="Record<string, string>">
  Custom headers to include in requests
</ResponseField>

<ResponseField name="timeout" type="number">
  Request timeout in milliseconds
</ResponseField>

<ResponseField name="retry" type="boolean">
  Whether to automatically retry failed requests
</ResponseField>

<ResponseField name="maxRetries" type="number">
  Maximum number of retry attempts
</ResponseField>


# HttpClientRequestOptions
Source: https://docs.x.com/xdks/typescript/reference/interfaces/HttpClientRequestOptions

Reference for the HttpClientRequestOptions TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

## Properties

<ParamField name="method" type="string" />

<ParamField name="headers" type="Record<string, string> | Headers" />

<ParamField name="body" type="string | Buffer | ArrayBuffer | ArrayBufferView" />

<ParamField name="signal" type="AbortSignal" />

<ParamField name="timeout" type="number" />


# HttpResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/HttpResponse

Reference for the HttpResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

## Properties

<ResponseField name="ok" type="boolean" />

<ResponseField name="status" type="number" />

<ResponseField name="statusText" type="string" />

<ResponseField name="headers" type="Headers" />

<ResponseField name="url" type="string" />

<ResponseField name="json" type="Promise<any>" />

<ResponseField name="text" type="Promise<string>" />

<ResponseField name="arrayBuffer" type="Promise<ArrayBuffer>" />


# PaginatedResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/PaginatedResponse

Reference for the PaginatedResponse TypeScript interface in the X API SDK. Represents the structure of a paginated API response from the X API.

Paginated response interface

Represents the structure of a paginated API response from the X API.

## Type parameters

| Name | Description                       |
| :--- | :-------------------------------- |
| `T`  | The type of items in the response |

## Properties

<ResponseField name="data" type="T[]">
  Array of items in the current page
</ResponseField>

<ResponseField name="meta" type="Object">
  Pagination metadata

  <Expandable title="properties">
    <ResponseField name="Name" type="Type | Description" />

    <ResponseField name="resultCount" type="number | Number of results in the current page" />

    <ResponseField name="nextToken" type="string | Token for fetching the next page" />

    <ResponseField name="previousToken" type="string | Token for fetching the previous page" />
  </Expandable>
</ResponseField>

<ResponseField name="includes" type="Record<string, any>">
  Additional included objects (users, tweets, etc.)
</ResponseField>

<ResponseField name="errors" type="any[]">
  Any errors in the response
</ResponseField>


# PaginationMeta
Source: https://docs.x.com/xdks/typescript/reference/interfaces/PaginationMeta

Reference for the PaginationMeta TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

Pagination metadata

## Properties

<ResponseField name="nextToken" type="string">
  Next page token
</ResponseField>

<ResponseField name="previousToken" type="string">
  Previous page token
</ResponseField>

<ResponseField name="totalCount" type="number">
  Total count
</ResponseField>

<ResponseField name="resultCount" type="number">
  Result count
</ResponseField>


# RequestOptions
Source: https://docs.x.com/xdks/typescript/reference/interfaces/RequestOptions

Reference for the RequestOptions TypeScript interface in the X API SDK. Request timeout in milliseconds Request signal for cancellation Return raw HTTP.

Request options for API calls

## Properties

<ParamField name="timeout" type="number">
  Request timeout in milliseconds
</ParamField>

<ParamField name="headers" type="Record<string, string>">
  Additional headers
</ParamField>

<ParamField name="signal" type="AbortSignal">
  Request signal for cancellation
</ParamField>

<ParamField name="body" type="string">
  Request body
</ParamField>

<ParamField name="raw" type="boolean">
  Return raw HTTP wrapper instead of parsed body
</ParamField>

<ParamField name="security" type="Record<string, string[]>[]">
  Security requirements for the endpoint (from OpenAPI spec) - used for smart auth selection
</ParamField>


# ActivityStreamingResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivityStreamingResponse

Schemas.ActivityStreamingResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ActivityStreamingResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# ActivitySubscription
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscription

Reference for the Schemas.ActivitySubscription TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ActivitySubscription

## Properties

<ResponseField name="createdAt" type="string" />

<ResponseField name="eventType" type="string" />

<ResponseField name="filter" type="ActivitySubscriptionFilter" />

<ResponseField name="subscriptionId" type="string" />

<ResponseField name="tag" type="string" />

<ResponseField name="updatedAt" type="string" />

<ResponseField name="webhookId" type="string" />


# ActivitySubscriptionCreateRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateRequest

TypeScript XDK `ActivitySubscriptionCreateRequest` interface reference — request schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).ActivitySubscriptionCreateRequest

## Properties

<ResponseField name="eventType" type="&#x22;profile.update.bio&#x22; | &#x22;profile.update.profile_picture&#x22; | &#x22;profile.update.banner_picture&#x22; | &#x22;profile.update.screenname&#x22; | &#x22;profile.update.geo&#x22; | &#x22;profile.update.url&#x22; | &#x22;profile.update.verified_badge&#x22; | &#x22;news.new&#x22; | &#x22;follow.follow&#x22; | &#x22;follow.unfollow&#x22; | &#x22;ProfileBioUpdate&#x22; | &#x22;ProfilePictureUpdate&#x22; | &#x22;ProfileBannerPictureUpdate&#x22; | &#x22;ProfileScreennameUpdate&#x22; | &#x22;ProfileGeoUpdate&#x22; | &#x22;ProfileUrlUpdate&#x22; | &#x22;ProfileVerifiedBadgeUpdate&#x22; | &#x22;NewsNew&#x22; | &#x22;FollowFollow&#x22; | &#x22;FollowUnfollow&#x22;" />

<ResponseField name="filter" type="ActivitySubscriptionFilter" />

<ResponseField name="tag" type="string" />

<ResponseField name="webhookId" type="string" />


# ActivitySubscriptionCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateResponse

TypeScript XDK `ActivitySubscriptionCreateResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).ActivitySubscriptionCreateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# ActivitySubscriptionDeleteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionDeleteResponse

TypeScript XDK `ActivitySubscriptionDeleteResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).ActivitySubscriptionDeleteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# ActivitySubscriptionFilter
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionFilter

Schemas.ActivitySubscriptionFilter TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ActivitySubscriptionFilter

## Properties

<ResponseField name="keyword" type="string" />

<ResponseField name="userId" type="string" />


# ActivitySubscriptionGetResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionGetResponse

TypeScript XDK `ActivitySubscriptionGetResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).ActivitySubscriptionGetResponse

## Properties

<ResponseField name="data" type="ActivitySubscription[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# ActivitySubscriptionUpdateRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateRequest

TypeScript XDK `ActivitySubscriptionUpdateRequest` interface reference — request schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).ActivitySubscriptionUpdateRequest

## Properties

<ResponseField name="tag" type="string" />

<ResponseField name="webhookId" type="string" />


# ActivitySubscriptionUpdateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateResponse

TypeScript XDK `ActivitySubscriptionUpdateResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).ActivitySubscriptionUpdateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />


# AddOrDeleteRulesResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.AddOrDeleteRulesResponse

Schemas.AddOrDeleteRulesResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).AddOrDeleteRulesResponse

## Properties

<ResponseField name="data" type="Rule[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="RulesResponseMetadata" />


# AddRulesRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.AddRulesRequest

Reference for the Schemas.AddRulesRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).AddRulesRequest

## Properties

<ResponseField name="add" type="RuleNoId[]" />


# AllowDownloadStatus
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.AllowDownloadStatus

Reference for the Schemas.AllowDownloadStatus TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).AllowDownloadStatus

## Properties

<ResponseField name="allowDownload" type="boolean" />


# AltText
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.AltText

Reference for the Schemas.AltText TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).AltText

## Properties

<ResponseField name="text" type="string" />


# Analytics
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Analytics

Reference for the Schemas.Analytics TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Analytics

## Properties

<ResponseField name="data" type="Record<string, any>[]" />

<ResponseField name="errors" type="Problem[]" />


# AppRulesCount
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.AppRulesCount

Reference for the Schemas.AppRulesCount TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).AppRulesCount

## Properties

<ResponseField name="clientAppId" type="string" />

<ResponseField name="ruleCount" type="number" />


# AudiencePolicy
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.AudiencePolicy

Reference for the Schemas.AudiencePolicy TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).AudiencePolicy

## Properties

<ResponseField name="creatorSubscriptions" type="&#x22;Any&#x22;[]" />

<ResponseField name="xSubscriptions" type="&#x22;Any&#x22;[]" />


# BookmarkAddRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.BookmarkAddRequest

Reference for the Schemas.BookmarkAddRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).BookmarkAddRequest

## Properties

<ResponseField name="tweetId" type="string" />


# BookmarkFolderPostsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.BookmarkFolderPostsResponse

Schemas.BookmarkFolderPostsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).BookmarkFolderPostsResponse

## Properties

<ResponseField name="data" type="Record<string, any>[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# BookmarkFoldersResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.BookmarkFoldersResponse

Schemas.BookmarkFoldersResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).BookmarkFoldersResponse

## Properties

<ResponseField name="data" type="Record<string, any>[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# BookmarkMutationResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.BookmarkMutationResponse

Schemas.BookmarkMutationResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).BookmarkMutationResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# CashtagFields
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CashtagFields

Reference for the Schemas.CashtagFields TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).CashtagFields

## Properties

<ResponseField name="tag" type="string" />


# ClientAppUsage
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ClientAppUsage

Reference for the Schemas.ClientAppUsage TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ClientAppUsage

## Properties

<ResponseField name="clientAppId" type="string" />

<ResponseField name="usage" type="UsageFields[]" />

<ResponseField name="usageResultCount" type="number" />


# Community
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Community

Reference for the Schemas.Community TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Community

## Properties

<ResponseField name="createdAt" type="string" />

<ResponseField name="id" type="string" />

<ResponseField name="name" type="string" />


# ComplianceJob
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ComplianceJob

Reference for the Schemas.ComplianceJob TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ComplianceJob

## Properties

<ResponseField name="createdAt" type="string" />

<ResponseField name="downloadExpiresAt" type="string" />

<ResponseField name="downloadUrl" type="string" />

<ResponseField name="id" type="string" />

<ResponseField name="name" type="string" />

<ResponseField name="status" type="ComplianceJobStatus" />

<ResponseField name="type" type="ComplianceJobType" />

<ResponseField name="uploadExpiresAt" type="string" />

<ResponseField name="uploadUrl" type="string" />


# Connection
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Connection

Reference for the Schemas.Connection TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Connection

## Properties

<ResponseField name="clientIp" type="string" />

<ResponseField name="connectedAt" type="string" />

<ResponseField name="disconnectReason" type="string" />

<ResponseField name="disconnectedAt" type="string" />

<ResponseField name="endpointName" type="string" />


# ContentExpiration
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ContentExpiration

Reference for the Schemas.ContentExpiration TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ContentExpiration

## Properties

<ResponseField name="timestampSec" type="number" />


# ContextAnnotation
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ContextAnnotation

Reference for the Schemas.ContextAnnotation TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ContextAnnotation

## Properties

<ResponseField name="domain" type="ContextAnnotationDomainFields" />

<ResponseField name="entity" type="ContextAnnotationEntityFields" />


# ContextAnnotationDomainFields
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ContextAnnotationDomainFields

Schemas.ContextAnnotationDomainFields TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ContextAnnotationDomainFields

## Properties

<ResponseField name="description" type="string" />

<ResponseField name="id" type="string" />

<ResponseField name="name" type="string" />


# ContextAnnotationEntityFields
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ContextAnnotationEntityFields

Schemas.ContextAnnotationEntityFields TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ContextAnnotationEntityFields

## Properties

<ResponseField name="description" type="string" />

<ResponseField name="id" type="string" />

<ResponseField name="name" type="string" />


# CreateAttachmentsMessageRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateAttachmentsMessageRequest

TypeScript XDK `CreateAttachmentsMessageRequest` interface reference — request schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).CreateAttachmentsMessageRequest

## Properties

<ResponseField name="attachments" type="DmAttachments" />

<ResponseField name="text" type="string" />


# CreateComplianceJobRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobRequest

Schemas.CreateComplianceJobRequest TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).CreateComplianceJobRequest

## Properties

<ResponseField name="name" type="string" />

<ResponseField name="resumable" type="boolean" />

<ResponseField name="type" type="&#x22;tweets&#x22; | &#x22;users&#x22;" />


# CreateComplianceJobResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobResponse

Schemas.CreateComplianceJobResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).CreateComplianceJobResponse

## Properties

<ResponseField name="data" type="ComplianceJob" />

<ResponseField name="errors" type="Problem[]" />


# CreateDmConversationRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateDmConversationRequest

Schemas.CreateDmConversationRequest TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).CreateDmConversationRequest

## Properties

<ResponseField name="conversationType" type="&#x22;Group&#x22;" />

<ResponseField name="message" type="any" />

<ResponseField name="participantIds" type="DmParticipants" />


# CreateDmEventResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse

Reference for the Schemas.CreateDmEventResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).CreateDmEventResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# CreateNoteRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateNoteRequest

Reference for the Schemas.CreateNoteRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).CreateNoteRequest

## Properties

<ResponseField name="info" type="NoteInfo" />

<ResponseField name="postId" type="string" />

<ResponseField name="testMode" type="boolean" />


# CreateNoteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateNoteResponse

Reference for the Schemas.CreateNoteResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).CreateNoteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# CreateTextMessageRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateTextMessageRequest

Schemas.CreateTextMessageRequest TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).CreateTextMessageRequest

## Properties

<ResponseField name="attachments" type="DmAttachments" />

<ResponseField name="text" type="string" />


# DeleteDmResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.DeleteDmResponse

Reference for the Schemas.DeleteDmResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).DeleteDmResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# DeleteNoteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.DeleteNoteResponse

Reference for the Schemas.DeleteNoteResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).DeleteNoteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# DeleteRulesRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.DeleteRulesRequest

Reference for the Schemas.DeleteRulesRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).DeleteRulesRequest

## Properties

<ResponseField name="delete" type="Record<string, any>" />


# DmEvent
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.DmEvent

Reference for the Schemas.DmEvent TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).DmEvent

## Properties

<ResponseField name="attachments" type="Record<string, any>" />

<ResponseField name="cashtags" type="any[]" />

<ResponseField name="createdAt" type="string" />

<ResponseField name="dmConversationId" type="string" />

<ResponseField name="eventType" type="string" />

<ResponseField name="hashtags" type="any[]" />

<ResponseField name="id" type="string" />

<ResponseField name="mentions" type="any[]" />

<ResponseField name="participantIds" type="string[]" />

<ResponseField name="referencedTweets" type="Record<string, any>[]" />

<ResponseField name="senderId" type="string" />

<ResponseField name="text" type="string" />

<ResponseField name="urls" type="any[]" />


# DmMediaAttachment
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.DmMediaAttachment

Reference for the Schemas.DmMediaAttachment TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).DmMediaAttachment

## Properties

<ResponseField name="mediaId" type="string" />


# DomainRestrictions
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.DomainRestrictions

Reference for the Schemas.DomainRestrictions TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).DomainRestrictions

## Properties

<ResponseField name="whitelist" type="string[]" />


# Engagement
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Engagement

Reference for the Schemas.Engagement TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Engagement

## Properties

<ResponseField name="errors" type="Record<string, any>[]" />

<ResponseField name="measurement" type="Record<string, any>" />


# EntityIndicesInclusiveExclusive
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.EntityIndicesInclusiveExclusive

TypeScript XDK `EntityIndicesInclusiveExclusive` interface reference —  schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).EntityIndicesInclusiveExclusive

## Properties

<ResponseField name="end" type="number" />

<ResponseField name="start" type="number" />


# EntityIndicesInclusiveInclusive
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.EntityIndicesInclusiveInclusive

TypeScript XDK `EntityIndicesInclusiveInclusive` interface reference —  schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).EntityIndicesInclusiveInclusive

## Properties

<ResponseField name="end" type="number" />

<ResponseField name="start" type="number" />


# Error
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Error

Reference for the Schemas.Error TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Error

## Properties

<ResponseField name="code" type="number" />

<ResponseField name="message" type="string" />


# EvaluateNoteRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.EvaluateNoteRequest

Reference for the Schemas.EvaluateNoteRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).EvaluateNoteRequest

## Properties

<ResponseField name="noteText" type="string" />

<ResponseField name="postId" type="string" />


# EvaluateNoteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.EvaluateNoteResponse

Reference for the Schemas.EvaluateNoteResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).EvaluateNoteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# Expansions
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Expansions

Reference for the Schemas.Expansions TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Expansions

## Properties

<ResponseField name="media" type="Media[]" />

<ResponseField name="places" type="Place[]" />

<ResponseField name="polls" type="Poll[]" />

<ResponseField name="topics" type="Topic[]" />

<ResponseField name="tweets" type="Tweet[]" />

<ResponseField name="users" type="User[]" />


# FilteredStreamingTweetResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.FilteredStreamingTweetResponse

TypeScript XDK `FilteredStreamingTweetResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).FilteredStreamingTweetResponse

## Properties

<ResponseField name="data" type="Tweet" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="matchingRules" type="Record<string, any>[]" />


# FollowActivityResponsePayload
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.FollowActivityResponsePayload

Schemas.FollowActivityResponsePayload TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).FollowActivityResponsePayload

## Properties

<ResponseField name="source" type="User" />

<ResponseField name="target" type="User" />


# FoundMediaOrigin
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.FoundMediaOrigin

Reference for the Schemas.FoundMediaOrigin TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).FoundMediaOrigin

## Properties

<ResponseField name="id" type="string" />

<ResponseField name="provider" type="string" />


# FullTextEntities
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.FullTextEntities

Reference for the Schemas.FullTextEntities TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).FullTextEntities

## Properties

<ResponseField name="annotations" type="any[]" />

<ResponseField name="cashtags" type="any[]" />

<ResponseField name="hashtags" type="any[]" />

<ResponseField name="mentions" type="any[]" />

<ResponseField name="urls" type="any[]" />


# Geo
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Geo

Reference for the Schemas.Geo TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Geo

## Properties

<ResponseField name="bbox" type="number[]" />

<ResponseField name="geometry" type="Point" />

<ResponseField name="properties" type="Record<string, any>" />

<ResponseField name="type" type="&#x22;Feature&#x22;" />


# Get2CommunitiesIdResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesIdResponse

Schemas.Get2CommunitiesIdResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2CommunitiesIdResponse

## Properties

<ResponseField name="data" type="Community" />

<ResponseField name="errors" type="Problem[]" />


# Get2CommunitiesSearchResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesSearchResponse

Schemas.Get2CommunitiesSearchResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2CommunitiesSearchResponse

## Properties

<ResponseField name="data" type="Community[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2ComplianceJobsIdResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsIdResponse

Schemas.Get2ComplianceJobsIdResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2ComplianceJobsIdResponse

## Properties

<ResponseField name="data" type="ComplianceJob" />

<ResponseField name="errors" type="Problem[]" />


# Get2ComplianceJobsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsResponse

Schemas.Get2ComplianceJobsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2ComplianceJobsResponse

## Properties

<ResponseField name="data" type="ComplianceJob[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2ConnectionsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2ConnectionsResponse

Schemas.Get2ConnectionsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2ConnectionsResponse

## Properties

<ResponseField name="data" type="Connection[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2DmConversationsIdDmEventsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsIdDmEventsResponse

TypeScript XDK `Get2DmConversationsIdDmEventsResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2DmConversationsIdDmEventsResponse

## Properties

<ResponseField name="data" type="DmEvent[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2DmConversationsWithParticipantIdDmEventsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsWithParticipantIdDmEventsResponse

Schemas.Get2DmConversationsWithParticipantIdDmEventsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2DmConversationsWithParticipantIdDmEventsResponse

## Properties

<ResponseField name="data" type="DmEvent[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2DmEventsEventIdResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2DmEventsEventIdResponse

Schemas.Get2DmEventsEventIdResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2DmEventsEventIdResponse

## Properties

<ResponseField name="data" type="DmEvent" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2DmEventsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2DmEventsResponse

Reference for the Schemas.Get2DmEventsResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2DmEventsResponse

## Properties

<ResponseField name="data" type="DmEvent[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2FdxAccountsAccountidContactResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidContactResponse

TypeScript XDK `Get2FdxAccountsAccountidContactResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2FdxAccountsAccountidContactResponse

## Properties

<ResponseField name="data" type="PlaidAccountContact" />

<ResponseField name="errors" type="Problem[]" />


# Get2FdxAccountsAccountidPayment_networksResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidPayment_networksResponse

`Get2FdxAccountsAccountidPayment_networksResponse` TypeScript XDK interface reference: fields, types, and required flags exposed by the X API v2 SDK client.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2FdxAccountsAccountidPayment\_networksResponse

## Properties

<ResponseField name="data" type="PlaidAccountPaymentNetwork[]" />

<ResponseField name="errors" type="Problem[]" />


# Get2FdxAccountsAccountidResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidResponse

TypeScript XDK `Get2FdxAccountsAccountidResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2FdxAccountsAccountidResponse

## Properties

<ResponseField name="data" type="PlaidAccount" />

<ResponseField name="errors" type="Problem[]" />


# Get2FdxAccountsAccountidTransactionsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidTransactionsResponse

TypeScript XDK `Get2FdxAccountsAccountidTransactionsResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2FdxAccountsAccountidTransactionsResponse

## Properties

<ResponseField name="data" type="PlaidAccountTransaction[]" />

<ResponseField name="errors" type="Problem[]" />


# Get2FdxCustomersCurrentResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2FdxCustomersCurrentResponse

TypeScript XDK `Get2FdxCustomersCurrentResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2FdxCustomersCurrentResponse

## Properties

<ResponseField name="data" type="PlaidCustomer" />

<ResponseField name="errors" type="Problem[]" />


# Get2Insights28hrResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2Insights28hrResponse

Schemas.Get2Insights28hrResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2Insights28hrResponse

## Properties

<ResponseField name="data" type="Engagement[]" />

<ResponseField name="errors" type="Problem[]" />


# Get2InsightsHistoricalResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2InsightsHistoricalResponse

TypeScript XDK `Get2InsightsHistoricalResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2InsightsHistoricalResponse

## Properties

<ResponseField name="data" type="Engagement[]" />

<ResponseField name="errors" type="Problem[]" />


# Get2LikesFirehoseStreamResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2LikesFirehoseStreamResponse

TypeScript XDK `Get2LikesFirehoseStreamResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2LikesFirehoseStreamResponse

## Properties

<ResponseField name="data" type="LikeWithTweetAuthor" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2LikesSample10StreamResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2LikesSample10StreamResponse

TypeScript XDK `Get2LikesSample10StreamResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2LikesSample10StreamResponse

## Properties

<ResponseField name="data" type="LikeWithTweetAuthor" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2ListsIdFollowersResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdFollowersResponse

Schemas.Get2ListsIdFollowersResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2ListsIdFollowersResponse

## Properties

<ResponseField name="data" type="User[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2ListsIdMembersResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdMembersResponse

Schemas.Get2ListsIdMembersResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2ListsIdMembersResponse

## Properties

<ResponseField name="data" type="User[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2ListsIdResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdResponse

Reference for the Schemas.Get2ListsIdResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2ListsIdResponse

## Properties

<ResponseField name="data" type="List" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2ListsIdTweetsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdTweetsResponse

Schemas.Get2ListsIdTweetsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2ListsIdTweetsResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2MediaAnalyticsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2MediaAnalyticsResponse

Schemas.Get2MediaAnalyticsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2MediaAnalyticsResponse

## Properties

<ResponseField name="data" type="MediaAnalytics" />

<ResponseField name="errors" type="Problem[]" />


# Get2MediaMediaKeyResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2MediaMediaKeyResponse

Schemas.Get2MediaMediaKeyResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2MediaMediaKeyResponse

## Properties

<ResponseField name="data" type="Media" />

<ResponseField name="errors" type="Problem[]" />


# Get2MediaResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2MediaResponse

Reference for the Schemas.Get2MediaResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2MediaResponse

## Properties

<ResponseField name="data" type="Media[]" />

<ResponseField name="errors" type="Problem[]" />


# Get2NewsIdResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2NewsIdResponse

Reference for the Schemas.Get2NewsIdResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2NewsIdResponse

## Properties

<ResponseField name="data" type="News" />

<ResponseField name="errors" type="Problem[]" />


# Get2NewsSearchResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2NewsSearchResponse

TypeScript XDK `Get2NewsSearchResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2NewsSearchResponse

## Properties

<ResponseField name="data" type="News[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2NotesSearchNotesWrittenResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchNotesWrittenResponse

TypeScript XDK `Get2NotesSearchNotesWrittenResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2NotesSearchNotesWrittenResponse

## Properties

<ResponseField name="data" type="Note[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2NotesSearchPostsEligibleForNotesResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchPostsEligibleForNotesResponse

TypeScript XDK `Get2NotesSearchPostsEligibleForNotesResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2NotesSearchPostsEligibleForNotesResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2SpacesByCreatorIdsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2SpacesByCreatorIdsResponse

TypeScript XDK `Get2SpacesByCreatorIdsResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2SpacesByCreatorIdsResponse

## Properties

<ResponseField name="data" type="Space[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2SpacesIdBuyersResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdBuyersResponse

Schemas.Get2SpacesIdBuyersResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2SpacesIdBuyersResponse

## Properties

<ResponseField name="data" type="User[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2SpacesIdResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdResponse

Reference for the Schemas.Get2SpacesIdResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2SpacesIdResponse

## Properties

<ResponseField name="data" type="Space" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2SpacesIdTweetsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdTweetsResponse

Schemas.Get2SpacesIdTweetsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2SpacesIdTweetsResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2SpacesResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2SpacesResponse

Reference for the Schemas.Get2SpacesResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2SpacesResponse

## Properties

<ResponseField name="data" type="Space[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2SpacesSearchResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2SpacesSearchResponse

Schemas.Get2SpacesSearchResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2SpacesSearchResponse

## Properties

<ResponseField name="data" type="Space[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2TrendsByWoeidWoeidResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TrendsByWoeidWoeidResponse

TypeScript XDK `Get2TrendsByWoeidWoeidResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TrendsByWoeidWoeidResponse

## Properties

<ResponseField name="data" type="Trend[]" />

<ResponseField name="errors" type="Problem[]" />


# Get2TweetsAnalyticsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsAnalyticsResponse

Schemas.Get2TweetsAnalyticsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsAnalyticsResponse

## Properties

<ResponseField name="data" type="Analytics" />

<ResponseField name="errors" type="Problem[]" />


# Get2TweetsCountsAllResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsAllResponse

Schemas.Get2TweetsCountsAllResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsCountsAllResponse

## Properties

<ResponseField name="data" type="SearchCount[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2TweetsCountsRecentResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsRecentResponse

TypeScript XDK `Get2TweetsCountsRecentResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsCountsRecentResponse

## Properties

<ResponseField name="data" type="SearchCount[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2TweetsFirehoseStreamLangEnResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangEnResponse

TypeScript XDK `Get2TweetsFirehoseStreamLangEnResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsFirehoseStreamLangEnResponse

## Properties

<ResponseField name="data" type="Tweet" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2TweetsFirehoseStreamLangJaResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangJaResponse

TypeScript XDK `Get2TweetsFirehoseStreamLangJaResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsFirehoseStreamLangJaResponse

## Properties

<ResponseField name="data" type="Tweet" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2TweetsFirehoseStreamLangKoResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangKoResponse

TypeScript XDK `Get2TweetsFirehoseStreamLangKoResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsFirehoseStreamLangKoResponse

## Properties

<ResponseField name="data" type="Tweet" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2TweetsFirehoseStreamLangPtResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangPtResponse

TypeScript XDK `Get2TweetsFirehoseStreamLangPtResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsFirehoseStreamLangPtResponse

## Properties

<ResponseField name="data" type="Tweet" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2TweetsFirehoseStreamResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamResponse

TypeScript XDK `Get2TweetsFirehoseStreamResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsFirehoseStreamResponse

## Properties

<ResponseField name="data" type="Tweet" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2TweetsIdLikingUsersResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdLikingUsersResponse

TypeScript XDK `Get2TweetsIdLikingUsersResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsIdLikingUsersResponse

## Properties

<ResponseField name="data" type="User[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2TweetsIdQuoteTweetsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdQuoteTweetsResponse

TypeScript XDK `Get2TweetsIdQuoteTweetsResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsIdQuoteTweetsResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2TweetsIdResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdResponse

Reference for the Schemas.Get2TweetsIdResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsIdResponse

## Properties

<ResponseField name="data" type="Tweet" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2TweetsIdRetweetedByResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetedByResponse

TypeScript XDK `Get2TweetsIdRetweetedByResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsIdRetweetedByResponse

## Properties

<ResponseField name="data" type="User[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2TweetsIdRetweetsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetsResponse

Schemas.Get2TweetsIdRetweetsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsIdRetweetsResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2TweetsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsResponse

Reference for the Schemas.Get2TweetsResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2TweetsSample10StreamResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSample10StreamResponse

TypeScript XDK `Get2TweetsSample10StreamResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsSample10StreamResponse

## Properties

<ResponseField name="data" type="Tweet" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2TweetsSampleStreamResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSampleStreamResponse

TypeScript XDK `Get2TweetsSampleStreamResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsSampleStreamResponse

## Properties

<ResponseField name="data" type="Tweet" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2TweetsSearchAllResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchAllResponse

Schemas.Get2TweetsSearchAllResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsSearchAllResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2TweetsSearchRecentResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchRecentResponse

TypeScript XDK `Get2TweetsSearchRecentResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsSearchRecentResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2TweetsSearchStreamResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchStreamResponse

TypeScript XDK `Get2TweetsSearchStreamResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsSearchStreamResponse

## Properties

<ResponseField name="data" type="Tweet" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2TweetsSearchStreamRulesCountsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchStreamRulesCountsResponse

TypeScript XDK `Get2TweetsSearchStreamRulesCountsResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2TweetsSearchStreamRulesCountsResponse

## Properties

<ResponseField name="data" type="RulesCount" />

<ResponseField name="errors" type="Problem[]" />


# Get2UsageTweetsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsageTweetsResponse

Schemas.Get2UsageTweetsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsageTweetsResponse

## Properties

<ResponseField name="data" type="Usage" />

<ResponseField name="errors" type="Problem[]" />


# Get2UsersByResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersByResponse

Reference for the Schemas.Get2UsersByResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersByResponse

## Properties

<ResponseField name="data" type="User[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2UsersByUsernameUsernameResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersByUsernameUsernameResponse

TypeScript XDK `Get2UsersByUsernameUsernameResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersByUsernameUsernameResponse

## Properties

<ResponseField name="data" type="User" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2UsersIdBlockingResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBlockingResponse

Schemas.Get2UsersIdBlockingResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdBlockingResponse

## Properties

<ResponseField name="data" type="User[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersIdBookmarksResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBookmarksResponse

Schemas.Get2UsersIdBookmarksResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdBookmarksResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersIdFollowedListsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowedListsResponse

TypeScript XDK `Get2UsersIdFollowedListsResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdFollowedListsResponse

## Properties

<ResponseField name="data" type="List[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersIdFollowersResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowersResponse

Schemas.Get2UsersIdFollowersResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdFollowersResponse

## Properties

<ResponseField name="data" type="User[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersIdFollowingResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowingResponse

Schemas.Get2UsersIdFollowingResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdFollowingResponse

## Properties

<ResponseField name="data" type="User[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersIdLikedTweetsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdLikedTweetsResponse

TypeScript XDK `Get2UsersIdLikedTweetsResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdLikedTweetsResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersIdListMembershipsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdListMembershipsResponse

TypeScript XDK `Get2UsersIdListMembershipsResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdListMembershipsResponse

## Properties

<ResponseField name="data" type="List[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersIdMentionsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMentionsResponse

Schemas.Get2UsersIdMentionsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdMentionsResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersIdMutingResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMutingResponse

Schemas.Get2UsersIdMutingResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdMutingResponse

## Properties

<ResponseField name="data" type="User[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersIdOwnedListsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdOwnedListsResponse

Schemas.Get2UsersIdOwnedListsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdOwnedListsResponse

## Properties

<ResponseField name="data" type="List[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersIdPinnedListsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdPinnedListsResponse

TypeScript XDK `Get2UsersIdPinnedListsResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdPinnedListsResponse

## Properties

<ResponseField name="data" type="List[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersIdResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdResponse

Reference for the Schemas.Get2UsersIdResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdResponse

## Properties

<ResponseField name="data" type="User" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2UsersIdTimelinesReverseChronologicalResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTimelinesReverseChronologicalResponse

`Get2UsersIdTimelinesReverseChronologicalResponse` TypeScript XDK interface reference: fields, types, and required flags exposed by the X API v2 SDK client.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdTimelinesReverseChronologicalResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersIdTweetsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTweetsResponse

Schemas.Get2UsersIdTweetsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersIdTweetsResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersMeResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersMeResponse

Reference for the Schemas.Get2UsersMeResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersMeResponse

## Properties

<ResponseField name="data" type="User" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2UsersPersonalizedTrendsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersPersonalizedTrendsResponse

TypeScript XDK `Get2UsersPersonalizedTrendsResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersPersonalizedTrendsResponse

zedTrendsResponse#data)

* [errors](/xdks/typescript/reference/interfaces/Schemas.Get2UsersPersonalizedTrendsResponse#errors)

## Properties

<ResponseField name="data" type="PersonalizedTrend[]" />

<ResponseField name="errors" type="Problem[]" />


# Get2UsersRepostsOfMeResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersRepostsOfMeResponse

Schemas.Get2UsersRepostsOfMeResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersRepostsOfMeResponse

## Properties

<ResponseField name="data" type="Tweet[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2UsersResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersResponse

Reference for the Schemas.Get2UsersResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersResponse

## Properties

<ResponseField name="data" type="User[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# Get2UsersSearchResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2UsersSearchResponse

Schemas.Get2UsersSearchResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2UsersSearchResponse

## Properties

<ResponseField name="data" type="User[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />

<ResponseField name="meta" type="Record<string, any>" />


# Get2WebhooksResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Get2WebhooksResponse

Reference for the Schemas.Get2WebhooksResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).Get2WebhooksResponse

## Properties

<ResponseField name="data" type="WebhookConfig[]" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="meta" type="Record<string, any>" />


# HashtagFields
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.HashtagFields

Reference for the Schemas.HashtagFields TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).HashtagFields

## Properties

<ResponseField name="tag" type="string" />


# KillAllConnectionsResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.KillAllConnectionsResponse

Schemas.KillAllConnectionsResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).KillAllConnectionsResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# LikeComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.LikeComplianceSchema

Reference for the Schemas.LikeComplianceSchema TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).LikeComplianceSchema

## Properties

<ResponseField name="delete" type="UnlikeComplianceSchema" />


# LikeWithTweetAuthor
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.LikeWithTweetAuthor

Reference for the Schemas.LikeWithTweetAuthor TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).LikeWithTweetAuthor

## Properties

<ResponseField name="createdAt" type="string" />

<ResponseField name="id" type="string" />

<ResponseField name="likedTweetId" type="string" />

<ResponseField name="timestampMs" type="number" />

<ResponseField name="tweetAuthorId" type="string" />


# List
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.List

Reference for the Schemas.List TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).List

## Properties

<ResponseField name="createdAt" type="string" />

<ResponseField name="description" type="string" />

<ResponseField name="followerCount" type="number" />

<ResponseField name="id" type="string" />

<ResponseField name="memberCount" type="number" />

<ResponseField name="name" type="string" />

<ResponseField name="ownerId" type="string" />

<ResponseField name="private" type="boolean" />


# ListAddUserRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ListAddUserRequest

Reference for the Schemas.ListAddUserRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ListAddUserRequest

## Properties

<ResponseField name="userId" type="string" />


# ListCreateRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ListCreateRequest

Reference for the Schemas.ListCreateRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ListCreateRequest

## Properties

<ResponseField name="description" type="string" />

<ResponseField name="name" type="string" />

<ResponseField name="private" type="boolean" />


# ListCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ListCreateResponse

Reference for the Schemas.ListCreateResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ListCreateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# ListDeleteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ListDeleteResponse

Reference for the Schemas.ListDeleteResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ListDeleteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# ListFollowedRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ListFollowedRequest

Reference for the Schemas.ListFollowedRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ListFollowedRequest

## Properties

<ResponseField name="listId" type="string" />


# ListFollowedResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ListFollowedResponse

Reference for the Schemas.ListFollowedResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ListFollowedResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# ListMutateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ListMutateResponse

Reference for the Schemas.ListMutateResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ListMutateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# ListPinnedRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ListPinnedRequest

Reference for the Schemas.ListPinnedRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ListPinnedRequest

## Properties

<ResponseField name="listId" type="string" />


# ListPinnedResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ListPinnedResponse

Reference for the Schemas.ListPinnedResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ListPinnedResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# ListUnpinResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ListUnpinResponse

Reference for the Schemas.ListUnpinResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ListUnpinResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# ListUpdateRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ListUpdateRequest

Reference for the Schemas.ListUpdateRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ListUpdateRequest

## Properties

<ResponseField name="description" type="string" />

<ResponseField name="name" type="string" />

<ResponseField name="private" type="boolean" />


# ListUpdateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ListUpdateResponse

Reference for the Schemas.ListUpdateResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ListUpdateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# ManagementInfo
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ManagementInfo

Reference for the Schemas.ManagementInfo TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ManagementInfo

## Properties

<ResponseField name="managed" type="boolean" />


# Media
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Media

Reference for the Schemas.Media TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Media

## Properties

<ResponseField name="height" type="number" />

<ResponseField name="mediaKey" type="string" />

<ResponseField name="type" type="string" />

<ResponseField name="width" type="number" />


# MediaAnalytics
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.MediaAnalytics

Reference for the Schemas.MediaAnalytics TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).MediaAnalytics

## Properties

<ResponseField name="data" type="Record<string, any>[]" />

<ResponseField name="errors" type="Problem[]" />


# MediaMetrics
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.MediaMetrics

Reference for the Schemas.MediaMetrics TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).MediaMetrics

## Properties

<ResponseField name="ctaUrlClicks" type="number" />

<ResponseField name="ctaWatchClicks" type="number" />

<ResponseField name="playFromTap" type="number" />

<ResponseField name="playback25" type="number" />

<ResponseField name="playback50" type="number" />

<ResponseField name="playback75" type="number" />

<ResponseField name="playbackComplete" type="number" />

<ResponseField name="playbackStart" type="number" />

<ResponseField name="videoViews" type="number" />

<ResponseField name="watchTimeMs" type="number" />


# MediaTimestampedMetrics
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.MediaTimestampedMetrics

Schemas.MediaTimestampedMetrics TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).MediaTimestampedMetrics

## Properties

<ResponseField name="metrics" type="MediaMetrics" />

<ResponseField name="timestamp" type="string" />


# MediaUploadAppendResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.MediaUploadAppendResponse

Schemas.MediaUploadAppendResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).MediaUploadAppendResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# MediaUploadConfigRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.MediaUploadConfigRequest

Schemas.MediaUploadConfigRequest TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).MediaUploadConfigRequest

## Properties

<ResponseField name="additionalOwners" type="string[]" />

<ResponseField name="mediaCategory" type="MediaCategory" />

<ResponseField name="mediaType" type="&#x22;video/mp4&#x22; | &#x22;video/webm&#x22; | &#x22;video/mp2t&#x22; | &#x22;video/quicktime&#x22; | &#x22;text/srt&#x22; | &#x22;text/vtt&#x22; | &#x22;image/jpeg&#x22; | &#x22;image/gif&#x22; | &#x22;image/bmp&#x22; | &#x22;image/png&#x22; | &#x22;image/webp&#x22; | &#x22;image/pjpeg&#x22; | &#x22;image/tiff&#x22; | &#x22;model/gltf-binary&#x22; | &#x22;model/vnd.usdz+zip&#x22;" />

<ResponseField name="shared" type="boolean" />

<ResponseField name="totalBytes" type="number" />


# MediaUploadRequestOneShot
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.MediaUploadRequestOneShot

Schemas.MediaUploadRequestOneShot TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).MediaUploadRequestOneShot

## Properties

<ResponseField name="additionalOwners" type="string[]" />

<ResponseField name="media" type="any" />

<ResponseField name="mediaCategory" type="MediaCategoryOneShot" />

<ResponseField name="mediaType" type="&#x22;text/srt&#x22; | &#x22;text/vtt&#x22; | &#x22;image/jpeg&#x22; | &#x22;image/bmp&#x22; | &#x22;image/png&#x22; | &#x22;image/webp&#x22; | &#x22;image/pjpeg&#x22; | &#x22;image/tiff&#x22;" />

<ResponseField name="shared" type="boolean" />


# MediaUploadResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse

Reference for the Schemas.MediaUploadResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).MediaUploadResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# MentionFields
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.MentionFields

Reference for the Schemas.MentionFields TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).MentionFields

## Properties

<ResponseField name="id" type="string" />

<ResponseField name="username" type="string" />


# MetadataCreateRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.MetadataCreateRequest

Reference for the Schemas.MetadataCreateRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).MetadataCreateRequest

## Properties

<ResponseField name="id" type="string" />

<ResponseField name="metadata" type="Record<string, any>" />


# MetadataCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.MetadataCreateResponse

TypeScript XDK `MetadataCreateResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).MetadataCreateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# Metrics
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Metrics

Reference for the Schemas.Metrics TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Metrics

## Properties

<ResponseField name="appInstallAttempts" type="number" />

<ResponseField name="appOpens" type="number" />

<ResponseField name="detailExpands" type="number" />

<ResponseField name="emailTweet" type="number" />

<ResponseField name="engagements" type="number" />

<ResponseField name="follows" type="number" />

<ResponseField name="hashtagClicks" type="number" />

<ResponseField name="impressions" type="number" />

<ResponseField name="likes" type="number" />

<ResponseField name="linkClicks" type="number" />

<ResponseField name="mediaEngagements" type="number" />

<ResponseField name="mediaViews" type="number" />

<ResponseField name="permalinkClicks" type="number" />

<ResponseField name="profileVisits" type="number" />

<ResponseField name="quoteTweets" type="number" />

<ResponseField name="replies" type="number" />

<ResponseField name="retweets" type="number" />

<ResponseField name="urlClicks" type="number" />

<ResponseField name="userProfileClicks" type="number" />


# MuteUserMutationResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.MuteUserMutationResponse

Schemas.MuteUserMutationResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).MuteUserMutationResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# MuteUserRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.MuteUserRequest

Reference for the Schemas.MuteUserRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).MuteUserRequest

## Properties

<ResponseField name="targetUserId" type="string" />


# News
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.News

Reference for the Schemas.News TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).News

## Properties

<ResponseField name="category" type="string" />

<ResponseField name="clusterPostsResults" type="Record<string, any>[]" />

<ResponseField name="contexts" type="Record<string, any>" />

<ResponseField name="disclaimer" type="string" />

<ResponseField name="hook" type="string" />

<ResponseField name="keywords" type="string[]" />

<ResponseField name="lastUpdatedAtMs" type="string" />

<ResponseField name="name" type="string" />

<ResponseField name="restId" type="string" />

<ResponseField name="summary" type="string" />


# NewsActivityResponsePayload
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.NewsActivityResponsePayload

Schemas.NewsActivityResponsePayload TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).NewsActivityResponsePayload

## Properties

<ResponseField name="category" type="string" />

<ResponseField name="headline" type="string" />

<ResponseField name="hook" type="string" />

<ResponseField name="summary" type="string" />


# Note
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Note

Reference for the Schemas.Note TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Note

## Properties

<ResponseField name="id" type="string" />

<ResponseField name="info" type="NoteInfo" />

<ResponseField name="postId" type="string" />

<ResponseField name="status" type="NoteRatingStatus" />

<ResponseField name="testResult" type="NoteTestResult" />


# NoteInfo
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.NoteInfo

Reference for the Schemas.NoteInfo TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).NoteInfo

## Properties

<ResponseField name="classification" type="NoteClassification" />

<ResponseField name="misleadingTags" type="MisleadingTags[]" />

<ResponseField name="text" type="string" />

<ResponseField name="trustworthySources" type="boolean" />


# NoteTestResult
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.NoteTestResult

Reference for the Schemas.NoteTestResult TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).NoteTestResult

## Properties

<ResponseField name="evaluatorScoreBucket" type="string" />

<ResponseField name="evaluatorType" type="string" />


# PersonalizedTrend
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.PersonalizedTrend

TypeScript XDK reference for the `PersonalizedTrend` interface, listing each field, its type, and whether it's required in the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).PersonalizedTrend

zedTrend#category)

* [postCount](/xdks/typescript/reference/interfaces/Schemas.PersonalizedTrend#postcount)
* [trendName](/xdks/typescript/reference/interfaces/Schemas.PersonalizedTrend#trendname)
* [trendingSince](/xdks/typescript/reference/interfaces/Schemas.PersonalizedTrend#trendingsince)

## Properties

<ResponseField name="category" type="string" />

<ResponseField name="postCount" type="number" />

<ResponseField name="trendName" type="string" />

<ResponseField name="trendingSince" type="string" />


# Place
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Place

Reference for the Schemas.Place TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Place

## Properties

<ResponseField name="containedWithin" type="string[]" />

<ResponseField name="country" type="string" />

<ResponseField name="countryCode" type="string" />

<ResponseField name="fullName" type="string" />

<ResponseField name="geo" type="Geo" />

<ResponseField name="id" type="string" />

<ResponseField name="name" type="string" />

<ResponseField name="placeType" type="PlaceType" />


# PlaidAccount
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.PlaidAccount

Reference for the Schemas.PlaidAccount TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).PlaidAccount

## Properties

<ResponseField name="accountCategory" type="string" />

<ResponseField name="accountId" type="string" />

<ResponseField name="accountNumberDisplay" type="string" />

<ResponseField name="accountType" type="string" />

<ResponseField name="availableBalance" type="number" />

<ResponseField name="currency" type="PlaidCurrency" />

<ResponseField name="currentBalance" type="number" />

<ResponseField name="nickname" type="string" />

<ResponseField name="productName" type="string" />

<ResponseField name="status" type="string" />


# PlaidAccountContact
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.PlaidAccountContact

Reference for the Schemas.PlaidAccountContact TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).PlaidAccountContact

## Properties

<ResponseField name="addresses" type="PlaidAddress[]" />

<ResponseField name="emails" type="string[]" />

<ResponseField name="name" type="PlaidName" />

<ResponseField name="relationship" type="string" />

<ResponseField name="telephones" type="PlaidTelephone[]" />


# PlaidAccountPaymentNetwork
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.PlaidAccountPaymentNetwork

Schemas.PlaidAccountPaymentNetwork TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).PlaidAccountPaymentNetwork

## Properties

<ResponseField name="bankId" type="string" />

<ResponseField name="identifier" type="string" />

<ResponseField name="transferIn" type="boolean" />

<ResponseField name="transferOut" type="boolean" />

<ResponseField name="type" type="string" />


# PlaidAccountTransaction
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.PlaidAccountTransaction

Schemas.PlaidAccountTransaction TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).PlaidAccountTransaction

## Properties

<ResponseField name="accountCategory" type="string" />

<ResponseField name="amount" type="number" />

<ResponseField name="debitCreditMemo" type="string" />

<ResponseField name="description" type="string" />

<ResponseField name="postedTimestamp" type="string" />

<ResponseField name="status" type="string" />

<ResponseField name="transactionId" type="string" />

<ResponseField name="transactionTimestamp" type="string" />


# PlaidAddress
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.PlaidAddress

Reference for the Schemas.PlaidAddress TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).PlaidAddress

## Properties

<ResponseField name="city" type="string" />

<ResponseField name="country" type="string" />

<ResponseField name="line1" type="string" />

<ResponseField name="line2" type="string" />

<ResponseField name="postalCode" type="string" />

<ResponseField name="region" type="string" />


# PlaidCurrency
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.PlaidCurrency

Reference for the Schemas.PlaidCurrency TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).PlaidCurrency

## Properties

<ResponseField name="currencyCode" type="string" />


# PlaidCustomer
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.PlaidCustomer

Reference for the Schemas.PlaidCustomer TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).PlaidCustomer

## Properties

<ResponseField name="customerId" type="string" />


# PlaidName
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.PlaidName

Reference for the Schemas.PlaidName TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).PlaidName

## Properties

<ResponseField name="first" type="string" />

<ResponseField name="last" type="string" />


# PlaidTelephone
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.PlaidTelephone

Reference for the Schemas.PlaidTelephone TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).PlaidTelephone

## Properties

<ResponseField name="country" type="string" />

<ResponseField name="number" type="string" />

<ResponseField name="type" type="string" />


# Point
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Point

Reference for the Schemas.Point TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Point

## Properties

<ResponseField name="coordinates" type="Position" />

<ResponseField name="type" type="&#x22;Point&#x22;" />


# Poll
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Poll

Reference for the Schemas.Poll TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Poll

## Properties

<ResponseField name="durationMinutes" type="number" />

<ResponseField name="endDatetime" type="string" />

<ResponseField name="id" type="string" />

<ResponseField name="options" type="PollOption[]" />

<ResponseField name="votingStatus" type="&#x22;open&#x22; | &#x22;closed&#x22;" />


# PollOption
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.PollOption

Reference for the Schemas.PollOption TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).PollOption

## Properties

<ResponseField name="label" type="string" />

<ResponseField name="position" type="number" />

<ResponseField name="votes" type="number" />


# PreviewImage
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.PreviewImage

Reference for the Schemas.PreviewImage TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).PreviewImage

## Properties

<ResponseField name="mediaKey" type="Record<string, any>" />


# Problem
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Problem

Reference for the Schemas.Problem TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Problem

## Properties

<ResponseField name="detail" type="string" />

<ResponseField name="status" type="number" />

<ResponseField name="title" type="string" />

<ResponseField name="type" type="string" />


# ProcessingInfo
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ProcessingInfo

Reference for the Schemas.ProcessingInfo TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ProcessingInfo

## Properties

<ResponseField name="checkAfterSecs" type="number" />

<ResponseField name="progressPercent" type="number" />

<ResponseField name="state" type="&#x22;in_progress&#x22; | &#x22;failed&#x22; | &#x22;succeeded&#x22; | &#x22;pending&#x22;" />


# ProfileUpdateActivityResponsePayload
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ProfileUpdateActivityResponsePayload

TypeScript XDK `ProfileUpdateActivityResponsePayload` interface reference — webhook payload schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).ProfileUpdateActivityResponsePayload

## Properties

<ResponseField name="after" type="string" />

<ResponseField name="before" type="string" />


# ReplayJobCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ReplayJobCreateResponse

Schemas.ReplayJobCreateResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).ReplayJobCreateResponse

## Properties

<ResponseField name="createdAt" type="string" />

<ResponseField name="jobId" type="string" />


# Rule
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Rule

Reference for the Schemas.Rule TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Rule

## Properties

<ResponseField name="id" type="string" />

<ResponseField name="tag" type="string" />

<ResponseField name="value" type="string" />


# RuleNoId
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.RuleNoId

Reference for the Schemas.RuleNoId TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).RuleNoId

## Properties

<ResponseField name="tag" type="string" />

<ResponseField name="value" type="string" />


# RulesCount
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.RulesCount

Reference for the Schemas.RulesCount TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).RulesCount

## Properties

<ResponseField name="allProjectClientApps" type="AllProjectClientApps" />

<ResponseField name="capPerClientApp" type="number" />

<ResponseField name="capPerProject" type="number" />

<ResponseField name="clientAppRulesCount" type="AppRulesCount" />

<ResponseField name="projectRulesCount" type="number" />


# RulesLookupResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.RulesLookupResponse

Reference for the Schemas.RulesLookupResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).RulesLookupResponse

## Properties

<ResponseField name="data" type="Rule[]" />

<ResponseField name="meta" type="RulesResponseMetadata" />


# RulesResponseMetadata
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.RulesResponseMetadata

Reference for the Schemas.RulesResponseMetadata TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).RulesResponseMetadata

## Properties

<ResponseField name="nextToken" type="string" />

<ResponseField name="resultCount" type="number" />

<ResponseField name="sent" type="string" />

<ResponseField name="summary" type="any" />


# SearchCount
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.SearchCount

Reference for the Schemas.SearchCount TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).SearchCount

## Properties

<ResponseField name="end" type="string" />

<ResponseField name="start" type="string" />

<ResponseField name="tweetCount" type="number" />


# SensitiveMediaWarning
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.SensitiveMediaWarning

Reference for the Schemas.SensitiveMediaWarning TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).SensitiveMediaWarning

## Properties

<ResponseField name="adultContent" type="boolean" />

<ResponseField name="graphicViolence" type="boolean" />

<ResponseField name="other" type="boolean" />


# SharedInfo
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.SharedInfo

Reference for the Schemas.SharedInfo TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).SharedInfo

## Properties

<ResponseField name="shared" type="boolean" />


# Space
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Space

Reference for the Schemas.Space TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Space

## Properties

<ResponseField name="createdAt" type="string" />

<ResponseField name="creatorId" type="string" />

<ResponseField name="endedAt" type="string" />

<ResponseField name="hostIds" type="string[]" />

<ResponseField name="id" type="string" />

<ResponseField name="invitedUserIds" type="string[]" />

<ResponseField name="isTicketed" type="boolean" />

<ResponseField name="lang" type="string" />

<ResponseField name="participantCount" type="number" />

<ResponseField name="scheduledStart" type="string" />

<ResponseField name="speakerIds" type="string[]" />

<ResponseField name="startedAt" type="string" />

<ResponseField name="state" type="&#x22;live&#x22; | &#x22;scheduled&#x22; | &#x22;ended&#x22;" />

<ResponseField name="subscriberCount" type="number" />

<ResponseField name="title" type="string" />

<ResponseField name="topics" type="Record<string, any>[]" />

<ResponseField name="updatedAt" type="string" />


# Sticker
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Sticker

Reference for the Schemas.Sticker TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Sticker

## Properties

<ResponseField name="aspectRatio" type="number" />

<ResponseField name="groupAnnotationId" type="number" />

<ResponseField name="id" type="string" />

<ResponseField name="stickerSetAnnotationId" type="number" />

<ResponseField name="transformA" type="number" />

<ResponseField name="transformB" type="number" />

<ResponseField name="transformC" type="number" />

<ResponseField name="transformD" type="number" />

<ResponseField name="transformTx" type="number" />

<ResponseField name="transformTy" type="number" />


# StickerInfo
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.StickerInfo

Reference for the Schemas.StickerInfo TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).StickerInfo

## Properties

<ResponseField name="stickers" type="Sticker[]" />


# StreamingLikeResponseV2
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.StreamingLikeResponseV2

Schemas.StreamingLikeResponseV2 TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).StreamingLikeResponseV2

## Properties

<ResponseField name="data" type="LikeWithTweetAuthor" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# StreamingTweetResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.StreamingTweetResponse

TypeScript XDK `StreamingTweetResponse` interface reference — response schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).StreamingTweetResponse

## Properties

<ResponseField name="data" type="Tweet" />

<ResponseField name="errors" type="Problem[]" />

<ResponseField name="includes" type="Expansions" />


# SubscriptionsCountGetResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.SubscriptionsCountGetResponse

Schemas.SubscriptionsCountGetResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).SubscriptionsCountGetResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# SubscriptionsCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.SubscriptionsCreateResponse

Schemas.SubscriptionsCreateResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).SubscriptionsCreateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# SubscriptionsDeleteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.SubscriptionsDeleteResponse

Schemas.SubscriptionsDeleteResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).SubscriptionsDeleteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# SubscriptionsGetResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.SubscriptionsGetResponse

Schemas.SubscriptionsGetResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).SubscriptionsGetResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# SubscriptionsListGetResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.SubscriptionsListGetResponse

Schemas.SubscriptionsListGetResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).SubscriptionsListGetResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# Subtitles
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Subtitles

Reference for the Schemas.Subtitles TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Subtitles

## Properties

<ResponseField name="displayName" type="string" />

<ResponseField name="id" type="string" />

<ResponseField name="languageCode" type="string" />


# SubtitlesCreateRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateRequest

TypeScript XDK `SubtitlesCreateRequest` interface reference — request schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).SubtitlesCreateRequest

## Properties

<ResponseField name="id" type="string" />

<ResponseField name="mediaCategory" type="MediaCategorySubtitles" />

<ResponseField name="subtitles" type="Subtitles" />


# SubtitlesCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateResponse

Schemas.SubtitlesCreateResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).SubtitlesCreateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# SubtitlesDeleteRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteRequest

TypeScript XDK `SubtitlesDeleteRequest` interface reference — request schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).SubtitlesDeleteRequest

## Properties

<ResponseField name="id" type="string" />

<ResponseField name="languageCode" type="string" />

<ResponseField name="mediaCategory" type="MediaCategorySubtitles" />


# SubtitlesDeleteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteResponse

Schemas.SubtitlesDeleteResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).SubtitlesDeleteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# TimestampedMetrics
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TimestampedMetrics

Reference for the Schemas.TimestampedMetrics TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TimestampedMetrics

## Properties

<ResponseField name="metrics" type="Metrics" />

<ResponseField name="timestamp" type="string" />


# Topic
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Topic

Reference for the Schemas.Topic TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Topic

## Properties

<ResponseField name="description" type="string" />

<ResponseField name="id" type="string" />

<ResponseField name="name" type="string" />


# Trend
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Trend

Reference for the Schemas.Trend TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Trend

## Properties

<ResponseField name="trendName" type="string" />

<ResponseField name="tweetCount" type="number" />


# Tweet
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Tweet

Reference for the Schemas.Tweet TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Tweet

## Properties

<ResponseField name="attachments" type="Record<string, any>" />

<ResponseField name="authorId" type="string" />

<ResponseField name="communityId" type="string" />

<ResponseField name="contextAnnotations" type="ContextAnnotation[]" />

<ResponseField name="conversationId" type="string" />

<ResponseField name="createdAt" type="string" />

<ResponseField name="displayTextRange" type="DisplayTextRange" />

<ResponseField name="editControls" type="Record<string, any>" />

<ResponseField name="editHistoryTweetIds" type="string[]" />

<ResponseField name="entities" type="FullTextEntities" />

<ResponseField name="geo" type="Record<string, any>" />

<ResponseField name="id" type="string" />

<ResponseField name="inReplyToUserId" type="string" />

<ResponseField name="lang" type="string" />

<ResponseField name="nonPublicMetrics" type="Record<string, any>" />

<ResponseField name="noteTweet" type="Record<string, any>" />

<ResponseField name="organicMetrics" type="Record<string, any>" />

<ResponseField name="possiblySensitive" type="boolean" />

<ResponseField name="promotedMetrics" type="Record<string, any>" />

<ResponseField name="publicMetrics" type="Record<string, any>" />

<ResponseField name="referencedTweets" type="Record<string, any>[]" />

<ResponseField name="replySettings" type="ReplySettingsWithVerifiedUsers" />

<ResponseField name="scopes" type="Record<string, any>" />

<ResponseField name="source" type="string" />

<ResponseField name="suggestedSourceLinks" type="any[]" />

<ResponseField name="suggestedSourceLinksWithCounts" type="Record<string, any>" />

<ResponseField name="text" type="string" />

<ResponseField name="username" type="string" />

<ResponseField name="withheld" type="TweetWithheld" />


# TweetComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetComplianceSchema

Reference for the Schemas.TweetComplianceSchema TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetComplianceSchema

## Properties

<ResponseField name="eventAt" type="string" />

<ResponseField name="quoteTweetId" type="string" />

<ResponseField name="tweet" type="Record<string, any>" />


# TweetCreateRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetCreateRequest

Reference for the Schemas.TweetCreateRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetCreateRequest

## Properties

<ResponseField name="cardUri" type="string" />

<ResponseField name="communityId" type="string" />

<ResponseField name="directMessageDeepLink" type="string" />

<ResponseField name="editOptions" type="Record<string, any>" />

<ResponseField name="forSuperFollowersOnly" type="boolean" />

<ResponseField name="geo" type="Record<string, any>" />

<ResponseField name="media" type="Record<string, any>" />

<ResponseField name="nullcast" type="boolean" />

<ResponseField name="paidPartnership" type="boolean">
  Whether this Post is a paid partnership. When true, the Post will be labeled as a paid promotion.
</ResponseField>

<ResponseField name="poll" type="Record<string, any>" />

<ResponseField name="quoteTweetId" type="string" />

<ResponseField name="reply" type="Record<string, any>" />

<ResponseField name="replySettings" type="&#x22;mentionedUsers&#x22; | &#x22;following&#x22; | &#x22;subscribers&#x22; | &#x22;verified&#x22;" />

<ResponseField name="shareWithFollowers" type="boolean" />

<ResponseField name="text" type="string" />


# TweetCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetCreateResponse

Reference for the Schemas.TweetCreateResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetCreateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# TweetDeleteComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetDeleteComplianceSchema

Schemas.TweetDeleteComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetDeleteComplianceSchema

## Properties

<ResponseField name="delete" type="TweetComplianceSchema" />


# TweetDeleteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetDeleteResponse

Reference for the Schemas.TweetDeleteResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetDeleteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# TweetDropComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetDropComplianceSchema

Schemas.TweetDropComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetDropComplianceSchema

## Properties

<ResponseField name="drop" type="TweetComplianceSchema" />


# TweetEditComplianceObjectSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetEditComplianceObjectSchema

TypeScript XDK `TweetEditComplianceObjectSchema` interface reference — compliance schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetEditComplianceObjectSchema

## Properties

<ResponseField name="editTweetIds" type="string[]" />

<ResponseField name="eventAt" type="string" />

<ResponseField name="initialTweetId" type="string" />

<ResponseField name="tweet" type="Record<string, any>" />


# TweetEditComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetEditComplianceSchema

Schemas.TweetEditComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetEditComplianceSchema

## Properties

<ResponseField name="tweetEdit" type="TweetEditComplianceObjectSchema" />


# TweetHideRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetHideRequest

Reference for the Schemas.TweetHideRequest TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetHideRequest

## Properties

<ResponseField name="hidden" type="boolean" />


# TweetHideResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetHideResponse

Reference for the Schemas.TweetHideResponse TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetHideResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />


# TweetNotice
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetNotice

Reference for the Schemas.TweetNotice TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetNotice

## Properties

<ResponseField name="application" type="string" />

<ResponseField name="details" type="string" />

<ResponseField name="eventAt" type="string" />

<ResponseField name="eventType" type="string" />

<ResponseField name="extendedDetailsUrl" type="string" />

<ResponseField name="labelTitle" type="string" />

<ResponseField name="tweet" type="Record<string, any>" />


# TweetNoticeSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetNoticeSchema

Reference for the Schemas.TweetNoticeSchema TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetNoticeSchema

## Properties

<ResponseField name="publicTweetNotice" type="TweetNotice" />


# TweetTakedownComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetTakedownComplianceSchema

Schemas.TweetTakedownComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetTakedownComplianceSchema

## Properties

<ResponseField name="eventAt" type="string" />

<ResponseField name="quoteTweetId" type="string" />

<ResponseField name="tweet" type="Record<string, any>" />

<ResponseField name="withheldInCountries" type="string[]" />


# TweetUndropComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetUndropComplianceSchema

Schemas.TweetUndropComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetUndropComplianceSchema

## Properties

<ResponseField name="undrop" type="TweetComplianceSchema" />


# TweetUnviewable
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetUnviewable

Reference for the Schemas.TweetUnviewable TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetUnviewable

## Properties

<ResponseField name="application" type="string" />

<ResponseField name="eventAt" type="string" />

<ResponseField name="tweet" type="Record<string, any>" />


# TweetUnviewableSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetUnviewableSchema

Reference for the Schemas.TweetUnviewableSchema TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetUnviewableSchema

## Properties

<ResponseField name="publicTweetUnviewable" type="TweetUnviewable" />


# TweetWithheld
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetWithheld

Reference for the Schemas.TweetWithheld TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetWithheld

## Properties

<ResponseField name="copyright" type="boolean" />

<ResponseField name="countryCodes" type="string[]" />

<ResponseField name="scope" type="&#x22;tweet&#x22; | &#x22;user&#x22;" />


# TweetWithheldComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.TweetWithheldComplianceSchema

Schemas.TweetWithheldComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).TweetWithheldComplianceSchema

## Properties

<ResponseField name="withheld" type="TweetTakedownComplianceSchema" />


# UnlikeComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UnlikeComplianceSchema

TypeScript XDK `UnlikeComplianceSchema` interface reference — compliance schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).UnlikeComplianceSchema

## Properties

<ResponseField name="eventAt" type="string" />

<ResponseField name="favorite" type="Record<string, any>" />


# UploadSource
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UploadSource

Reference for the Schemas.UploadSource TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).UploadSource

## Properties

<ResponseField name="uploadSource" type="string" />


# UrlFields
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UrlFields

Reference for the Schemas.UrlFields TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).UrlFields

## Properties

<ResponseField name="description" type="string" />

<ResponseField name="displayUrl" type="string" />

<ResponseField name="expandedUrl" type="string" />

<ResponseField name="images" type="UrlImage[]" />

<ResponseField name="mediaKey" type="string" />

<ResponseField name="status" type="number" />

<ResponseField name="title" type="string" />

<ResponseField name="unwoundUrl" type="string" />

<ResponseField name="url" type="string" />


# UrlImage
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UrlImage

Reference for the Schemas.UrlImage TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).UrlImage

## Properties

<ResponseField name="height" type="number" />

<ResponseField name="url" type="string" />

<ResponseField name="width" type="number" />


# Usage
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Usage

Reference for the Schemas.Usage TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Usage

## Properties

<ResponseField name="capResetDay" type="number" />

<ResponseField name="dailyClientAppUsage" type="ClientAppUsage[]" />

<ResponseField name="dailyProjectUsage" type="Record<string, any>" />

<ResponseField name="projectCap" type="number" />

<ResponseField name="projectId" type="string" />

<ResponseField name="projectUsage" type="number" />


# UsageFields
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UsageFields

Reference for the Schemas.UsageFields TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).UsageFields

## Properties

<ResponseField name="date" type="string" />

<ResponseField name="usage" type="number" />


# User
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.User

Reference for the Schemas.User TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).User

## Properties

<ResponseField name="affiliation" type="Record<string, any>" />

<ResponseField name="connectionStatus" type="(&#x22;following&#x22; | &#x22;follow_request_received&#x22; | &#x22;follow_request_sent&#x22; | &#x22;blocking&#x22; | &#x22;followed_by&#x22; | &#x22;muting&#x22;)[]" />

<ResponseField name="createdAt" type="string" />

<ResponseField name="description" type="string" />

<ResponseField name="entities" type="Record<string, any>" />

<ResponseField name="id" type="string" />

<ResponseField name="location" type="string" />

<ResponseField name="mostRecentTweetId" type="string" />

<ResponseField name="name" type="string" />

<ResponseField name="pinnedTweetId" type="string" />

<ResponseField name="profileBannerUrl" type="string" />

<ResponseField name="profileImageUrl" type="string" />

<ResponseField name="protected" type="boolean" />

<ResponseField name="publicMetrics" type="Record<string, any>" />

<ResponseField name="receivesYourDm" type="boolean" />

<ResponseField name="subscriptionType" type="&#x22;Basic&#x22; | &#x22;Premium&#x22; | &#x22;PremiumPlus&#x22; | &#x22;None&#x22;" />

<ResponseField name="url" type="string" />

<ResponseField name="username" type="string" />

<ResponseField name="verified" type="boolean" />

<ResponseField name="verifiedType" type="&#x22;blue&#x22; | &#x22;government&#x22; | &#x22;business&#x22; | &#x22;none&#x22;" />

<ResponseField name="withheld" type="UserWithheld" />


# UserComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserComplianceSchema

Reference for the Schemas.UserComplianceSchema TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserComplianceSchema

## Properties

<ResponseField name="eventAt" type="string" />

<ResponseField name="user" type="Record<string, any>" />


# UserDeleteComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserDeleteComplianceSchema

Schemas.UserDeleteComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserDeleteComplianceSchema

## Properties

<ResponseField name="userDelete" type="UserComplianceSchema" />


# UserProfileModificationComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserProfileModificationComplianceSchema

TypeScript XDK `UserProfileModificationComplianceSchema` interface reference — compliance schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserProfileModificationComplianceSchema

## Properties

<ResponseField name="userProfileModification" type="UserProfileModificationObjectSchema" />


# UserProfileModificationObjectSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserProfileModificationObjectSchema

TypeScript XDK `UserProfileModificationObjectSchema` interface reference —  schema with fields, types, and required flags for the X API v2 SDK.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserProfileModificationObjectSchema

## Properties

<ResponseField name="eventAt" type="string" />

<ResponseField name="newValue" type="string" />

<ResponseField name="profileField" type="string" />

<ResponseField name="user" type="Record<string, any>" />


# UserProtectComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserProtectComplianceSchema

Schemas.UserProtectComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserProtectComplianceSchema

## Properties

<ResponseField name="userProtect" type="UserComplianceSchema" />


# UserScrubGeoObjectSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserScrubGeoObjectSchema

Schemas.UserScrubGeoObjectSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserScrubGeoObjectSchema

## Properties

<ResponseField name="eventAt" type="string" />

<ResponseField name="upToTweetId" type="string" />

<ResponseField name="user" type="Record<string, any>" />


# UserScrubGeoSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserScrubGeoSchema

Reference for the Schemas.UserScrubGeoSchema TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserScrubGeoSchema

## Properties

<ResponseField name="scrubGeo" type="UserScrubGeoObjectSchema" />


# UserSuspendComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserSuspendComplianceSchema

Schemas.UserSuspendComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserSuspendComplianceSchema

## Properties

<ResponseField name="userSuspend" type="UserComplianceSchema" />


# UserTakedownComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserTakedownComplianceSchema

Schemas.UserTakedownComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserTakedownComplianceSchema

## Properties

<ResponseField name="eventAt" type="string" />

<ResponseField name="user" type="Record<string, any>" />

<ResponseField name="withheldInCountries" type="string[]" />


# UserUndeleteComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserUndeleteComplianceSchema

Schemas.UserUndeleteComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserUndeleteComplianceSchema

## Properties

<ResponseField name="userUndelete" type="UserComplianceSchema" />


# UserUnprotectComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserUnprotectComplianceSchema

Schemas.UserUnprotectComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserUnprotectComplianceSchema

## Properties

<ResponseField name="userUnprotect" type="UserComplianceSchema" />


# UserUnsuspendComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserUnsuspendComplianceSchema

Schemas.UserUnsuspendComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserUnsuspendComplianceSchema

## Properties

<ResponseField name="userUnsuspend" type="UserComplianceSchema" />


# UserWithheld
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserWithheld

Reference for the Schemas.UserWithheld TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserWithheld

## Properties

<ResponseField name="countryCodes" type="string[]" />

<ResponseField name="scope" type="&#x22;user&#x22;" />


# UserWithheldComplianceSchema
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UserWithheldComplianceSchema

Schemas.UserWithheldComplianceSchema TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UserWithheldComplianceSchema

## Properties

<ResponseField name="userWithheld" type="UserTakedownComplianceSchema" />


# UsersDMBlockCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UsersDMBlockCreateResponse

Schemas.UsersDMBlockCreateResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UsersDMBlockCreateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# UsersDMUnBlockCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UsersDMUnBlockCreateResponse

Schemas.UsersDMUnBlockCreateResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UsersDMUnBlockCreateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# UsersFollowingCreateRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateRequest

Schemas.UsersFollowingCreateRequest TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UsersFollowingCreateRequest

## Properties

<ResponseField name="targetUserId" type="string" />


# UsersFollowingCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateResponse

Schemas.UsersFollowingCreateResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UsersFollowingCreateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# UsersFollowingDeleteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UsersFollowingDeleteResponse

Schemas.UsersFollowingDeleteResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UsersFollowingDeleteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# UsersLikesCreateRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateRequest

Schemas.UsersLikesCreateRequest TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UsersLikesCreateRequest

## Properties

<ResponseField name="tweetId" type="string" />


# UsersLikesCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateResponse

Schemas.UsersLikesCreateResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UsersLikesCreateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# UsersLikesDeleteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UsersLikesDeleteResponse

Schemas.UsersLikesDeleteResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UsersLikesDeleteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# UsersRetweetsCreateRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateRequest

Schemas.UsersRetweetsCreateRequest TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UsersRetweetsCreateRequest

## Properties

<ResponseField name="tweetId" type="string" />


# UsersRetweetsCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateResponse

Schemas.UsersRetweetsCreateResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UsersRetweetsCreateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# UsersRetweetsDeleteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsDeleteResponse

Schemas.UsersRetweetsDeleteResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).UsersRetweetsDeleteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# Variant
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Variant

Reference for the Schemas.Variant TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response payloads.

[Schemas](/xdks/typescript/reference/modules/Schemas).Variant

## Properties

<ResponseField name="bitRate" type="number" />

<ResponseField name="contentType" type="string" />

<ResponseField name="url" type="string" />


# WebhookConfig
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.WebhookConfig

Reference for the Schemas.WebhookConfig TypeScript interface in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).WebhookConfig

## Properties

<ResponseField name="createdAt" type="string" />

<ResponseField name="id" type="string" />

<ResponseField name="url" type="string" />

<ResponseField name="valid" type="boolean" />


# WebhookConfigCreateRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateRequest

Schemas.WebhookConfigCreateRequest TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).WebhookConfigCreateRequest

## Properties

<ResponseField name="url" type="string" />


# WebhookConfigCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateResponse

Schemas.WebhookConfigCreateResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).WebhookConfigCreateResponse

## Properties

<ResponseField name="createdAt" type="string" />

<ResponseField name="id" type="string" />

<ResponseField name="url" type="string" />

<ResponseField name="valid" type="boolean" />


# WebhookConfigDeleteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.WebhookConfigDeleteResponse

Schemas.WebhookConfigDeleteResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).WebhookConfigDeleteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# WebhookConfigPutResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.WebhookConfigPutResponse

Schemas.WebhookConfigPutResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).WebhookConfigPutResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# WebhookLinksCreateResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.WebhookLinksCreateResponse

Schemas.WebhookLinksCreateResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).WebhookLinksCreateResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# WebhookLinksDeleteResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.WebhookLinksDeleteResponse

Schemas.WebhookLinksDeleteResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).WebhookLinksDeleteResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# WebhookLinksGetResponse
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.WebhookLinksGetResponse

Schemas.WebhookLinksGetResponse TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).WebhookLinksGetResponse

## Properties

<ResponseField name="data" type="Record<string, any>" />

<ResponseField name="errors" type="Problem[]" />


# WebhookReplayCreateRequest
Source: https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.WebhookReplayCreateRequest

Schemas.WebhookReplayCreateRequest TypeScript interface reference in the X API SDK. Field definitions, types, and properties for X API request or response.

[Schemas](/xdks/typescript/reference/modules/Schemas).WebhookReplayCreateRequest

## Properties

<ResponseField name="fromDate" type="string" />

<ResponseField name="toDate" type="string" />

<ResponseField name="webhookId" type="string" />


# X API SDK v2.152 - v0.4.0
Source: https://docs.x.com/xdks/typescript/reference/modules

Reference for the modules module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

<AccordionGroup>
  <Accordion title="Interfaces">
    <Accordion title="Client">
      * [ClientConfig](/xdks/typescript/reference/interfaces/ClientConfig)
    </Accordion>

    <Accordion title="Http">
      * [HttpClientRequestOptions](/xdks/typescript/reference/interfaces/HttpClientRequestOptions)
      * [HttpResponse](/xdks/typescript/reference/interfaces/HttpResponse)
    </Accordion>

    <Accordion title="Misc">
      * [ApiResponse](/xdks/typescript/reference/interfaces/ApiResponse)
      * [PaginatedResponse](/xdks/typescript/reference/interfaces/PaginatedResponse)
      * [PaginationMeta](/xdks/typescript/reference/interfaces/PaginationMeta)
      * [RequestOptions](/xdks/typescript/reference/interfaces/RequestOptions)
      * [Schemas.ActivityStreamingResponse](/xdks/typescript/reference/interfaces/Schemas.ActivityStreamingResponse)
      * [Schemas.ActivitySubscription](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscription)
      * [Schemas.ActivitySubscriptionCreateRequest](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateRequest)
      * [Schemas.ActivitySubscriptionCreateResponse](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateResponse)
      * [Schemas.ActivitySubscriptionDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionDeleteResponse)
      * [Schemas.ActivitySubscriptionFilter](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionFilter)
      * [Schemas.ActivitySubscriptionGetResponse](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionGetResponse)
      * [Schemas.ActivitySubscriptionUpdateRequest](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateRequest)
      * [Schemas.ActivitySubscriptionUpdateResponse](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateResponse)
      * [Schemas.AddOrDeleteRulesResponse](/xdks/typescript/reference/interfaces/Schemas.AddOrDeleteRulesResponse)
      * [Schemas.AddRulesRequest](/xdks/typescript/reference/interfaces/Schemas.AddRulesRequest)
      * [Schemas.AllowDownloadStatus](/xdks/typescript/reference/interfaces/Schemas.AllowDownloadStatus)
      * [Schemas.AltText](/xdks/typescript/reference/interfaces/Schemas.AltText)
      * [Schemas.Analytics](/xdks/typescript/reference/interfaces/Schemas.Analytics)
      * [Schemas.AppRulesCount](/xdks/typescript/reference/interfaces/Schemas.AppRulesCount)
      * [Schemas.AudiencePolicy](/xdks/typescript/reference/interfaces/Schemas.AudiencePolicy)
      * [Schemas.BookmarkAddRequest](/xdks/typescript/reference/interfaces/Schemas.BookmarkAddRequest)
      * [Schemas.BookmarkFolderPostsResponse](/xdks/typescript/reference/interfaces/Schemas.BookmarkFolderPostsResponse)
      * [Schemas.BookmarkFoldersResponse](/xdks/typescript/reference/interfaces/Schemas.BookmarkFoldersResponse)
      * [Schemas.BookmarkMutationResponse](/xdks/typescript/reference/interfaces/Schemas.BookmarkMutationResponse)
      * [Schemas.CashtagFields](/xdks/typescript/reference/interfaces/Schemas.CashtagFields)
      * [Schemas.ClientAppUsage](/xdks/typescript/reference/interfaces/Schemas.ClientAppUsage)
      * [Schemas.Community](/xdks/typescript/reference/interfaces/Schemas.Community)
      * [Schemas.ComplianceJob](/xdks/typescript/reference/interfaces/Schemas.ComplianceJob)
      * [Schemas.Connection](/xdks/typescript/reference/interfaces/Schemas.Connection)
      * [Schemas.ContentExpiration](/xdks/typescript/reference/interfaces/Schemas.ContentExpiration)
      * [Schemas.ContextAnnotation](/xdks/typescript/reference/interfaces/Schemas.ContextAnnotation)
      * [Schemas.ContextAnnotationDomainFields](/xdks/typescript/reference/interfaces/Schemas.ContextAnnotationDomainFields)
      * [Schemas.ContextAnnotationEntityFields](/xdks/typescript/reference/interfaces/Schemas.ContextAnnotationEntityFields)
      * [Schemas.CreateAttachmentsMessageRequest](/xdks/typescript/reference/interfaces/Schemas.CreateAttachmentsMessageRequest)
      * [Schemas.CreateComplianceJobRequest](/xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobRequest)
      * [Schemas.CreateComplianceJobResponse](/xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobResponse)
      * [Schemas.CreateDmConversationRequest](/xdks/typescript/reference/interfaces/Schemas.CreateDmConversationRequest)
      * [Schemas.CreateDmEventResponse](/xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse)
      * [Schemas.CreateNoteRequest](/xdks/typescript/reference/interfaces/Schemas.CreateNoteRequest)
      * [Schemas.CreateNoteResponse](/xdks/typescript/reference/interfaces/Schemas.CreateNoteResponse)
      * [Schemas.CreateTextMessageRequest](/xdks/typescript/reference/interfaces/Schemas.CreateTextMessageRequest)
      * [Schemas.DeleteDmResponse](/xdks/typescript/reference/interfaces/Schemas.DeleteDmResponse)
      * [Schemas.DeleteNoteResponse](/xdks/typescript/reference/interfaces/Schemas.DeleteNoteResponse)
      * [Schemas.DeleteRulesRequest](/xdks/typescript/reference/interfaces/Schemas.DeleteRulesRequest)
      * [Schemas.DmEvent](/xdks/typescript/reference/interfaces/Schemas.DmEvent)
      * [Schemas.DmMediaAttachment](/xdks/typescript/reference/interfaces/Schemas.DmMediaAttachment)
      * [Schemas.DomainRestrictions](/xdks/typescript/reference/interfaces/Schemas.DomainRestrictions)
      * [Schemas.Engagement](/xdks/typescript/reference/interfaces/Schemas.Engagement)
      * [Schemas.EntityIndicesInclusiveExclusive](/xdks/typescript/reference/interfaces/Schemas.EntityIndicesInclusiveExclusive)
      * [Schemas.EntityIndicesInclusiveInclusive](/xdks/typescript/reference/interfaces/Schemas.EntityIndicesInclusiveInclusive)
      * [Schemas.Error](/xdks/typescript/reference/interfaces/Schemas.Error)
      * [Schemas.EvaluateNoteRequest](/xdks/typescript/reference/interfaces/Schemas.EvaluateNoteRequest)
      * [Schemas.EvaluateNoteResponse](/xdks/typescript/reference/interfaces/Schemas.EvaluateNoteResponse)
      * [Schemas.Expansions](/xdks/typescript/reference/interfaces/Schemas.Expansions)
      * [Schemas.FilteredStreamingTweetResponse](/xdks/typescript/reference/interfaces/Schemas.FilteredStreamingTweetResponse)
      * [Schemas.FollowActivityResponsePayload](/xdks/typescript/reference/interfaces/Schemas.FollowActivityResponsePayload)
      * [Schemas.FoundMediaOrigin](/xdks/typescript/reference/interfaces/Schemas.FoundMediaOrigin)
      * [Schemas.FullTextEntities](/xdks/typescript/reference/interfaces/Schemas.FullTextEntities)
      * [Schemas.Geo](/xdks/typescript/reference/interfaces/Schemas.Geo)
      * [Schemas.Get2CommunitiesIdResponse](/xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesIdResponse)
      * [Schemas.Get2CommunitiesSearchResponse](/xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesSearchResponse)
      * [Schemas.Get2ComplianceJobsIdResponse](/xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsIdResponse)
      * [Schemas.Get2ComplianceJobsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsResponse)
      * [Schemas.Get2ConnectionsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2ConnectionsResponse)
      * [Schemas.Get2DmConversationsIdDmEventsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsIdDmEventsResponse)
      * [Schemas.Get2DmConversationsWithParticipantIdDmEventsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsWithParticipantIdDmEventsResponse)
      * [Schemas.Get2DmEventsEventIdResponse](/xdks/typescript/reference/interfaces/Schemas.Get2DmEventsEventIdResponse)
      * [Schemas.Get2DmEventsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2DmEventsResponse)
      * [Schemas.Get2FdxAccountsAccountidContactResponse](/xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidContactResponse)
      * [Schemas.Get2FdxAccountsAccountidPayment\_networksResponse](/xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidPayment_networksResponse)
      * [Schemas.Get2FdxAccountsAccountidResponse](/xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidResponse)
      * [Schemas.Get2FdxAccountsAccountidTransactionsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidTransactionsResponse)
      * [Schemas.Get2FdxCustomersCurrentResponse](/xdks/typescript/reference/interfaces/Schemas.Get2FdxCustomersCurrentResponse)
      * [Schemas.Get2Insights28hrResponse](/xdks/typescript/reference/interfaces/Schemas.Get2Insights28hrResponse)
      * [Schemas.Get2InsightsHistoricalResponse](/xdks/typescript/reference/interfaces/Schemas.Get2InsightsHistoricalResponse)
      * [Schemas.Get2LikesFirehoseStreamResponse](/xdks/typescript/reference/interfaces/Schemas.Get2LikesFirehoseStreamResponse)
      * [Schemas.Get2LikesSample10StreamResponse](/xdks/typescript/reference/interfaces/Schemas.Get2LikesSample10StreamResponse)
      * [Schemas.Get2ListsIdFollowersResponse](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdFollowersResponse)
      * [Schemas.Get2ListsIdMembersResponse](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdMembersResponse)
      * [Schemas.Get2ListsIdResponse](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdResponse)
      * [Schemas.Get2ListsIdTweetsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdTweetsResponse)
      * [Schemas.Get2MediaAnalyticsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2MediaAnalyticsResponse)
      * [Schemas.Get2MediaMediaKeyResponse](/xdks/typescript/reference/interfaces/Schemas.Get2MediaMediaKeyResponse)
      * [Schemas.Get2MediaResponse](/xdks/typescript/reference/interfaces/Schemas.Get2MediaResponse)
      * [Schemas.Get2NewsIdResponse](/xdks/typescript/reference/interfaces/Schemas.Get2NewsIdResponse)
      * [Schemas.Get2NewsSearchResponse](/xdks/typescript/reference/interfaces/Schemas.Get2NewsSearchResponse)
      * [Schemas.Get2NotesSearchNotesWrittenResponse](/xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchNotesWrittenResponse)
      * [Schemas.Get2NotesSearchPostsEligibleForNotesResponse](/xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchPostsEligibleForNotesResponse)
      * [Schemas.Get2SpacesByCreatorIdsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesByCreatorIdsResponse)
      * [Schemas.Get2SpacesIdBuyersResponse](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdBuyersResponse)
      * [Schemas.Get2SpacesIdResponse](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdResponse)
      * [Schemas.Get2SpacesIdTweetsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdTweetsResponse)
      * [Schemas.Get2SpacesResponse](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesResponse)
      * [Schemas.Get2SpacesSearchResponse](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesSearchResponse)
      * [Schemas.Get2TrendsByWoeidWoeidResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TrendsByWoeidWoeidResponse)
      * [Schemas.Get2TweetsAnalyticsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsAnalyticsResponse)
      * [Schemas.Get2TweetsCountsAllResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsAllResponse)
      * [Schemas.Get2TweetsCountsRecentResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsRecentResponse)
      * [Schemas.Get2TweetsFirehoseStreamLangEnResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangEnResponse)
      * [Schemas.Get2TweetsFirehoseStreamLangJaResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangJaResponse)
      * [Schemas.Get2TweetsFirehoseStreamLangKoResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangKoResponse)
      * [Schemas.Get2TweetsFirehoseStreamLangPtResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangPtResponse)
      * [Schemas.Get2TweetsFirehoseStreamResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamResponse)
      * [Schemas.Get2TweetsIdLikingUsersResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdLikingUsersResponse)
      * [Schemas.Get2TweetsIdQuoteTweetsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdQuoteTweetsResponse)
      * [Schemas.Get2TweetsIdResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdResponse)
      * [Schemas.Get2TweetsIdRetweetedByResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetedByResponse)
      * [Schemas.Get2TweetsIdRetweetsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetsResponse)
      * [Schemas.Get2TweetsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsResponse)
      * [Schemas.Get2TweetsSample10StreamResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSample10StreamResponse)
      * [Schemas.Get2TweetsSampleStreamResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSampleStreamResponse)
      * [Schemas.Get2TweetsSearchAllResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchAllResponse)
      * [Schemas.Get2TweetsSearchRecentResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchRecentResponse)
      * [Schemas.Get2TweetsSearchStreamResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchStreamResponse)
      * [Schemas.Get2TweetsSearchStreamRulesCountsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchStreamRulesCountsResponse)
      * [Schemas.Get2UsageTweetsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsageTweetsResponse)
      * [Schemas.Get2UsersByResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersByResponse)
      * [Schemas.Get2UsersByUsernameUsernameResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersByUsernameUsernameResponse)
      * [Schemas.Get2UsersIdBlockingResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBlockingResponse)
      * [Schemas.Get2UsersIdBookmarksResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBookmarksResponse)
      * [Schemas.Get2UsersIdFollowedListsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowedListsResponse)
      * [Schemas.Get2UsersIdFollowersResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowersResponse)
      * [Schemas.Get2UsersIdFollowingResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowingResponse)
      * [Schemas.Get2UsersIdLikedTweetsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdLikedTweetsResponse)
      * [Schemas.Get2UsersIdListMembershipsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdListMembershipsResponse)
      * [Schemas.Get2UsersIdMentionsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMentionsResponse)
      * [Schemas.Get2UsersIdMutingResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMutingResponse)
      * [Schemas.Get2UsersIdOwnedListsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdOwnedListsResponse)
      * [Schemas.Get2UsersIdPinnedListsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdPinnedListsResponse)
      * [Schemas.Get2UsersIdResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdResponse)
      * [Schemas.Get2UsersIdTimelinesReverseChronologicalResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTimelinesReverseChronologicalResponse)
      * [Schemas.Get2UsersIdTweetsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTweetsResponse)
      * [Schemas.Get2UsersMeResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersMeResponse)
      * [Schemas.Get2UsersPersonalizedTrendsResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersPersonalizedTrendsResponse)
      * [Schemas.Get2UsersRepostsOfMeResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersRepostsOfMeResponse)
      * [Schemas.Get2UsersResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersResponse)
      * [Schemas.Get2UsersSearchResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersSearchResponse)
      * [Schemas.Get2WebhooksResponse](/xdks/typescript/reference/interfaces/Schemas.Get2WebhooksResponse)
      * [Schemas.HashtagFields](/xdks/typescript/reference/interfaces/Schemas.HashtagFields)
      * [Schemas.KillAllConnectionsResponse](/xdks/typescript/reference/interfaces/Schemas.KillAllConnectionsResponse)
      * [Schemas.LikeComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.LikeComplianceSchema)
      * [Schemas.LikeWithTweetAuthor](/xdks/typescript/reference/interfaces/Schemas.LikeWithTweetAuthor)
      * [Schemas.List](/xdks/typescript/reference/interfaces/Schemas.List)
      * [Schemas.ListAddUserRequest](/xdks/typescript/reference/interfaces/Schemas.ListAddUserRequest)
      * [Schemas.ListCreateRequest](/xdks/typescript/reference/interfaces/Schemas.ListCreateRequest)
      * [Schemas.ListCreateResponse](/xdks/typescript/reference/interfaces/Schemas.ListCreateResponse)
      * [Schemas.ListDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.ListDeleteResponse)
      * [Schemas.ListFollowedRequest](/xdks/typescript/reference/interfaces/Schemas.ListFollowedRequest)
      * [Schemas.ListFollowedResponse](/xdks/typescript/reference/interfaces/Schemas.ListFollowedResponse)
      * [Schemas.ListMutateResponse](/xdks/typescript/reference/interfaces/Schemas.ListMutateResponse)
      * [Schemas.ListPinnedRequest](/xdks/typescript/reference/interfaces/Schemas.ListPinnedRequest)
      * [Schemas.ListPinnedResponse](/xdks/typescript/reference/interfaces/Schemas.ListPinnedResponse)
      * [Schemas.ListUnpinResponse](/xdks/typescript/reference/interfaces/Schemas.ListUnpinResponse)
      * [Schemas.ListUpdateRequest](/xdks/typescript/reference/interfaces/Schemas.ListUpdateRequest)
      * [Schemas.ListUpdateResponse](/xdks/typescript/reference/interfaces/Schemas.ListUpdateResponse)
      * [Schemas.ManagementInfo](/xdks/typescript/reference/interfaces/Schemas.ManagementInfo)
      * [Schemas.Media](/xdks/typescript/reference/interfaces/Schemas.Media)
      * [Schemas.MediaAnalytics](/xdks/typescript/reference/interfaces/Schemas.MediaAnalytics)
      * [Schemas.MediaMetrics](/xdks/typescript/reference/interfaces/Schemas.MediaMetrics)
      * [Schemas.MediaTimestampedMetrics](/xdks/typescript/reference/interfaces/Schemas.MediaTimestampedMetrics)
      * [Schemas.MediaUploadAppendResponse](/xdks/typescript/reference/interfaces/Schemas.MediaUploadAppendResponse)
      * [Schemas.MediaUploadConfigRequest](/xdks/typescript/reference/interfaces/Schemas.MediaUploadConfigRequest)
      * [Schemas.MediaUploadRequestOneShot](/xdks/typescript/reference/interfaces/Schemas.MediaUploadRequestOneShot)
      * [Schemas.MediaUploadResponse](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)
      * [Schemas.MentionFields](/xdks/typescript/reference/interfaces/Schemas.MentionFields)
      * [Schemas.MetadataCreateRequest](/xdks/typescript/reference/interfaces/Schemas.MetadataCreateRequest)
      * [Schemas.MetadataCreateResponse](/xdks/typescript/reference/interfaces/Schemas.MetadataCreateResponse)
      * [Schemas.Metrics](/xdks/typescript/reference/interfaces/Schemas.Metrics)
      * [Schemas.MuteUserMutationResponse](/xdks/typescript/reference/interfaces/Schemas.MuteUserMutationResponse)
      * [Schemas.MuteUserRequest](/xdks/typescript/reference/interfaces/Schemas.MuteUserRequest)
      * [Schemas.News](/xdks/typescript/reference/interfaces/Schemas.News)
      * [Schemas.NewsActivityResponsePayload](/xdks/typescript/reference/interfaces/Schemas.NewsActivityResponsePayload)
      * [Schemas.Note](/xdks/typescript/reference/interfaces/Schemas.Note)
      * [Schemas.NoteInfo](/xdks/typescript/reference/interfaces/Schemas.NoteInfo)
      * [Schemas.NoteTestResult](/xdks/typescript/reference/interfaces/Schemas.NoteTestResult)
      * [Schemas.PersonalizedTrend](/xdks/typescript/reference/interfaces/Schemas.PersonalizedTrend)
      * [Schemas.Place](/xdks/typescript/reference/interfaces/Schemas.Place)
      * [Schemas.PlaidAccount](/xdks/typescript/reference/interfaces/Schemas.PlaidAccount)
      * [Schemas.PlaidAccountContact](/xdks/typescript/reference/interfaces/Schemas.PlaidAccountContact)
      * [Schemas.PlaidAccountPaymentNetwork](/xdks/typescript/reference/interfaces/Schemas.PlaidAccountPaymentNetwork)
      * [Schemas.PlaidAccountTransaction](/xdks/typescript/reference/interfaces/Schemas.PlaidAccountTransaction)
      * [Schemas.PlaidAddress](/xdks/typescript/reference/interfaces/Schemas.PlaidAddress)
      * [Schemas.PlaidCurrency](/xdks/typescript/reference/interfaces/Schemas.PlaidCurrency)
      * [Schemas.PlaidCustomer](/xdks/typescript/reference/interfaces/Schemas.PlaidCustomer)
      * [Schemas.PlaidName](/xdks/typescript/reference/interfaces/Schemas.PlaidName)
      * [Schemas.PlaidTelephone](/xdks/typescript/reference/interfaces/Schemas.PlaidTelephone)
      * [Schemas.Point](/xdks/typescript/reference/interfaces/Schemas.Point)
      * [Schemas.Poll](/xdks/typescript/reference/interfaces/Schemas.Poll)
      * [Schemas.PollOption](/xdks/typescript/reference/interfaces/Schemas.PollOption)
      * [Schemas.PreviewImage](/xdks/typescript/reference/interfaces/Schemas.PreviewImage)
      * [Schemas.Problem](/xdks/typescript/reference/interfaces/Schemas.Problem)
      * [Schemas.ProcessingInfo](/xdks/typescript/reference/interfaces/Schemas.ProcessingInfo)
      * [Schemas.ProfileUpdateActivityResponsePayload](/xdks/typescript/reference/interfaces/Schemas.ProfileUpdateActivityResponsePayload)
      * [Schemas.ReplayJobCreateResponse](/xdks/typescript/reference/interfaces/Schemas.ReplayJobCreateResponse)
      * [Schemas.Rule](/xdks/typescript/reference/interfaces/Schemas.Rule)
      * [Schemas.RuleNoId](/xdks/typescript/reference/interfaces/Schemas.RuleNoId)
      * [Schemas.RulesCount](/xdks/typescript/reference/interfaces/Schemas.RulesCount)
      * [Schemas.RulesLookupResponse](/xdks/typescript/reference/interfaces/Schemas.RulesLookupResponse)
      * [Schemas.RulesResponseMetadata](/xdks/typescript/reference/interfaces/Schemas.RulesResponseMetadata)
      * [Schemas.SearchCount](/xdks/typescript/reference/interfaces/Schemas.SearchCount)
      * [Schemas.SensitiveMediaWarning](/xdks/typescript/reference/interfaces/Schemas.SensitiveMediaWarning)
      * [Schemas.SharedInfo](/xdks/typescript/reference/interfaces/Schemas.SharedInfo)
      * [Schemas.Space](/xdks/typescript/reference/interfaces/Schemas.Space)
      * [Schemas.Sticker](/xdks/typescript/reference/interfaces/Schemas.Sticker)
      * [Schemas.StickerInfo](/xdks/typescript/reference/interfaces/Schemas.StickerInfo)
      * [Schemas.StreamingLikeResponseV2](/xdks/typescript/reference/interfaces/Schemas.StreamingLikeResponseV2)
      * [Schemas.StreamingTweetResponse](/xdks/typescript/reference/interfaces/Schemas.StreamingTweetResponse)
      * [Schemas.SubscriptionsCountGetResponse](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsCountGetResponse)
      * [Schemas.SubscriptionsCreateResponse](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsCreateResponse)
      * [Schemas.SubscriptionsDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsDeleteResponse)
      * [Schemas.SubscriptionsGetResponse](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsGetResponse)
      * [Schemas.SubscriptionsListGetResponse](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsListGetResponse)
      * [Schemas.Subtitles](/xdks/typescript/reference/interfaces/Schemas.Subtitles)
      * [Schemas.SubtitlesCreateRequest](/xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateRequest)
      * [Schemas.SubtitlesCreateResponse](/xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateResponse)
      * [Schemas.SubtitlesDeleteRequest](/xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteRequest)
      * [Schemas.SubtitlesDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteResponse)
      * [Schemas.TimestampedMetrics](/xdks/typescript/reference/interfaces/Schemas.TimestampedMetrics)
      * [Schemas.Topic](/xdks/typescript/reference/interfaces/Schemas.Topic)
      * [Schemas.Trend](/xdks/typescript/reference/interfaces/Schemas.Trend)
      * [Schemas.Tweet](/xdks/typescript/reference/interfaces/Schemas.Tweet)
      * [Schemas.TweetComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetComplianceSchema)
      * [Schemas.TweetCreateRequest](/xdks/typescript/reference/interfaces/Schemas.TweetCreateRequest)
      * [Schemas.TweetCreateResponse](/xdks/typescript/reference/interfaces/Schemas.TweetCreateResponse)
      * [Schemas.TweetDeleteComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetDeleteComplianceSchema)
      * [Schemas.TweetDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.TweetDeleteResponse)
      * [Schemas.TweetDropComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetDropComplianceSchema)
      * [Schemas.TweetEditComplianceObjectSchema](/xdks/typescript/reference/interfaces/Schemas.TweetEditComplianceObjectSchema)
      * [Schemas.TweetEditComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetEditComplianceSchema)
      * [Schemas.TweetHideRequest](/xdks/typescript/reference/interfaces/Schemas.TweetHideRequest)
      * [Schemas.TweetHideResponse](/xdks/typescript/reference/interfaces/Schemas.TweetHideResponse)
      * [Schemas.TweetNotice](/xdks/typescript/reference/interfaces/Schemas.TweetNotice)
      * [Schemas.TweetNoticeSchema](/xdks/typescript/reference/interfaces/Schemas.TweetNoticeSchema)
      * [Schemas.TweetTakedownComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetTakedownComplianceSchema)
      * [Schemas.TweetUndropComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetUndropComplianceSchema)
      * [Schemas.TweetUnviewable](/xdks/typescript/reference/interfaces/Schemas.TweetUnviewable)
      * [Schemas.TweetUnviewableSchema](/xdks/typescript/reference/interfaces/Schemas.TweetUnviewableSchema)
      * [Schemas.TweetWithheld](/xdks/typescript/reference/interfaces/Schemas.TweetWithheld)
      * [Schemas.TweetWithheldComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetWithheldComplianceSchema)
      * [Schemas.UnlikeComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UnlikeComplianceSchema)
      * [Schemas.UploadSource](/xdks/typescript/reference/interfaces/Schemas.UploadSource)
      * [Schemas.UrlFields](/xdks/typescript/reference/interfaces/Schemas.UrlFields)
      * [Schemas.UrlImage](/xdks/typescript/reference/interfaces/Schemas.UrlImage)
      * [Schemas.Usage](/xdks/typescript/reference/interfaces/Schemas.Usage)
      * [Schemas.UsageFields](/xdks/typescript/reference/interfaces/Schemas.UsageFields)
      * [Schemas.User](/xdks/typescript/reference/interfaces/Schemas.User)
      * [Schemas.UserComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserComplianceSchema)
      * [Schemas.UserDeleteComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserDeleteComplianceSchema)
      * [Schemas.UserProfileModificationComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserProfileModificationComplianceSchema)
      * [Schemas.UserProfileModificationObjectSchema](/xdks/typescript/reference/interfaces/Schemas.UserProfileModificationObjectSchema)
      * [Schemas.UserProtectComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserProtectComplianceSchema)
      * [Schemas.UserScrubGeoObjectSchema](/xdks/typescript/reference/interfaces/Schemas.UserScrubGeoObjectSchema)
      * [Schemas.UserScrubGeoSchema](/xdks/typescript/reference/interfaces/Schemas.UserScrubGeoSchema)
      * [Schemas.UserSuspendComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserSuspendComplianceSchema)
      * [Schemas.UserTakedownComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserTakedownComplianceSchema)
      * [Schemas.UserUndeleteComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserUndeleteComplianceSchema)
      * [Schemas.UserUnprotectComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserUnprotectComplianceSchema)
      * [Schemas.UserUnsuspendComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserUnsuspendComplianceSchema)
      * [Schemas.UserWithheld](/xdks/typescript/reference/interfaces/Schemas.UserWithheld)
      * [Schemas.UserWithheldComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserWithheldComplianceSchema)
      * [Schemas.UsersDMBlockCreateResponse](/xdks/typescript/reference/interfaces/Schemas.UsersDMBlockCreateResponse)
      * [Schemas.UsersDMUnBlockCreateResponse](/xdks/typescript/reference/interfaces/Schemas.UsersDMUnBlockCreateResponse)
      * [Schemas.UsersFollowingCreateRequest](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateRequest)
      * [Schemas.UsersFollowingCreateResponse](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateResponse)
      * [Schemas.UsersFollowingDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingDeleteResponse)
      * [Schemas.UsersLikesCreateRequest](/xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateRequest)
      * [Schemas.UsersLikesCreateResponse](/xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateResponse)
      * [Schemas.UsersLikesDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.UsersLikesDeleteResponse)
      * [Schemas.UsersRetweetsCreateRequest](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateRequest)
      * [Schemas.UsersRetweetsCreateResponse](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateResponse)
      * [Schemas.UsersRetweetsDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsDeleteResponse)
      * [Schemas.Variant](/xdks/typescript/reference/interfaces/Schemas.Variant)
      * [Schemas.WebhookConfig](/xdks/typescript/reference/interfaces/Schemas.WebhookConfig)
      * [Schemas.WebhookConfigCreateRequest](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateRequest)
      * [Schemas.WebhookConfigCreateResponse](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateResponse)
      * [Schemas.WebhookConfigDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigDeleteResponse)
      * [Schemas.WebhookConfigPutResponse](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigPutResponse)
      * [Schemas.WebhookLinksCreateResponse](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksCreateResponse)
      * [Schemas.WebhookLinksDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksDeleteResponse)
      * [Schemas.WebhookLinksGetResponse](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksGetResponse)
      * [Schemas.WebhookReplayCreateRequest](/xdks/typescript/reference/interfaces/Schemas.WebhookReplayCreateRequest)
    </Accordion>
  </Accordion>

  <Accordion title="Classes">
    <Accordion title="AccountActivity">
      * [AccountActivityClient](/xdks/typescript/reference/classes/AccountActivityClient)
    </Accordion>

    <Accordion title="Activity">
      * [ActivityClient](/xdks/typescript/reference/classes/ActivityClient)
    </Accordion>

    <Accordion title="Client">
      * [Client](/xdks/typescript/reference/classes/Client)
    </Accordion>

    <Accordion title="Clients">
      * [NewsClient](/xdks/typescript/reference/classes/NewsClient)
    </Accordion>

    <Accordion title="Communities">
      * [CommunitiesClient](/xdks/typescript/reference/classes/CommunitiesClient)
    </Accordion>

    <Accordion title="CommunityNotes">
      * [CommunityNotesClient](/xdks/typescript/reference/classes/CommunityNotesClient)
    </Accordion>

    <Accordion title="Compliance">
      * [ComplianceClient](/xdks/typescript/reference/classes/ComplianceClient)
    </Accordion>

    <Accordion title="Connections">
      * [ConnectionsClient](/xdks/typescript/reference/classes/ConnectionsClient)
    </Accordion>

    <Accordion title="Core">
      * [ApiError](/xdks/typescript/reference/classes/ApiError)
    </Accordion>

    <Accordion title="DirectMessages">
      * [DirectMessagesClient](/xdks/typescript/reference/classes/DirectMessagesClient)
    </Accordion>

    <Accordion title="General">
      * [GeneralClient](/xdks/typescript/reference/classes/GeneralClient)
    </Accordion>

    <Accordion title="Http">
      * [HttpClient](/xdks/typescript/reference/classes/HttpClient)
    </Accordion>

    <Accordion title="Lists">
      * [ListsClient](/xdks/typescript/reference/classes/ListsClient)
    </Accordion>

    <Accordion title="Media">
      * [MediaClient](/xdks/typescript/reference/classes/MediaClient)
    </Accordion>

    <Accordion title="Pagination">
      * [EventPaginator](/xdks/typescript/reference/classes/EventPaginator)
      * [PostPaginator](/xdks/typescript/reference/classes/PostPaginator)
      * [UserPaginator](/xdks/typescript/reference/classes/UserPaginator)
    </Accordion>

    <Accordion title="Paginator">
      * [Paginator](/xdks/typescript/reference/classes/Paginator)
    </Accordion>

    <Accordion title="Posts">
      * [PostsClient](/xdks/typescript/reference/classes/PostsClient)
    </Accordion>

    <Accordion title="Spaces">
      * [SpacesClient](/xdks/typescript/reference/classes/SpacesClient)
    </Accordion>

    <Accordion title="Stream">
      * [StreamClient](/xdks/typescript/reference/classes/StreamClient)
    </Accordion>

    <Accordion title="Trends">
      * [TrendsClient](/xdks/typescript/reference/classes/TrendsClient)
    </Accordion>

    <Accordion title="Usage">
      * [UsageClient](/xdks/typescript/reference/classes/UsageClient)
    </Accordion>

    <Accordion title="Users">
      * [UsersClient](/xdks/typescript/reference/classes/UsersClient)
    </Accordion>

    <Accordion title="Webhooks">
      * [WebhooksClient](/xdks/typescript/reference/classes/WebhooksClient)
    </Accordion>
  </Accordion>
</AccordionGroup>


# Namespace: AccountActivity
Source: https://docs.x.com/xdks/typescript/reference/modules/AccountActivity

Reference for the AccountActivity module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### GetSubscriptionsResponse

Ƭ **GetSubscriptionsResponse**: [`SubscriptionsListGetResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsListGetResponse)

Response for getSubscriptions

#### Defined in

[account\_activity/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/models.ts#L18)

***

### DeleteSubscriptionResponse

Ƭ **DeleteSubscriptionResponse**: [`SubscriptionsDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsDeleteResponse)

Response for deleteSubscription

#### Defined in

[account\_activity/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/models.ts#L24)

***

### ValidateSubscriptionResponse

Ƭ **ValidateSubscriptionResponse**: [`SubscriptionsGetResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsGetResponse)

Response for validateSubscription

#### Defined in

[account\_activity/models.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/models.ts#L30)

***

### CreateSubscriptionRequest

Ƭ **CreateSubscriptionRequest**: [`SubscriptionsCreateRequest`](/xdks/typescript/reference/modules/Schemas#subscriptionscreaterequest)

Request for createSubscription

#### Defined in

[account\_activity/models.ts:36](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/models.ts#L36)

***

### CreateSubscriptionResponse

Ƭ **CreateSubscriptionResponse**: [`SubscriptionsCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsCreateResponse)

Response for createSubscription

#### Defined in

[account\_activity/models.ts:42](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/models.ts#L42)

***

### CreateReplayJobResponse

Ƭ **CreateReplayJobResponse**: [`ReplayJobCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.ReplayJobCreateResponse)

Response for createReplayJob

#### Defined in

[account\_activity/models.ts:48](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/models.ts#L48)

***

### GetSubscriptionCountResponse

Ƭ **GetSubscriptionCountResponse**: [`SubscriptionsCountGetResponse`](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsCountGetResponse)

Response for getSubscriptionCount

#### Defined in

[account\_activity/models.ts:54](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/account_activity/models.ts#L54)


# Namespace: Activity
Source: https://docs.x.com/xdks/typescript/reference/modules/Activity

Reference for the Activity module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### GetSubscriptionsResponse

Ƭ **GetSubscriptionsResponse**: [`ActivitySubscriptionGetResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionGetResponse)

Response for getSubscriptions

#### Defined in

[activity/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/models.ts#L18)

***

### CreateSubscriptionRequest

Ƭ **CreateSubscriptionRequest**: [`ActivitySubscriptionCreateRequest`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateRequest)

Request for createSubscription

#### Defined in

[activity/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/models.ts#L24)

***

### CreateSubscriptionResponse

Ƭ **CreateSubscriptionResponse**: [`ActivitySubscriptionCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateResponse)

Response for createSubscription

#### Defined in

[activity/models.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/models.ts#L30)

***

### StreamResponse

Ƭ **StreamResponse**: [`ActivityStreamingResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivityStreamingResponse)

Response for stream

#### Defined in

[activity/models.ts:36](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/models.ts#L36)

***

### UpdateSubscriptionRequest

Ƭ **UpdateSubscriptionRequest**: [`ActivitySubscriptionUpdateRequest`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateRequest)

Request for updateSubscription

#### Defined in

[activity/models.ts:42](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/models.ts#L42)

***

### UpdateSubscriptionResponse

Ƭ **UpdateSubscriptionResponse**: [`ActivitySubscriptionUpdateResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateResponse)

Response for updateSubscription

#### Defined in

[activity/models.ts:48](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/models.ts#L48)

***

### DeleteSubscriptionResponse

Ƭ **DeleteSubscriptionResponse**: [`ActivitySubscriptionDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionDeleteResponse)

Response for deleteSubscription

#### Defined in

[activity/models.ts:54](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/activity/models.ts#L54)


# Namespace: Communities
Source: https://docs.x.com/xdks/typescript/reference/modules/Communities

Reference for the Communities module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### SearchResponse

Ƭ **SearchResponse**: [`Get2CommunitiesSearchResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesSearchResponse)

Response for search

#### Defined in

[communities/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/communities/models.ts#L18)

***

### GetByIdResponse

Ƭ **GetByIdResponse**: [`Get2CommunitiesIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesIdResponse)

Response for getById

#### Defined in

[communities/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/communities/models.ts#L24)


# Namespace: CommunityNotes
Source: https://docs.x.com/xdks/typescript/reference/modules/CommunityNotes

Reference for the CommunityNotes module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### SearchEligiblePostsResponse

Ƭ **SearchEligiblePostsResponse**: [`Get2NotesSearchPostsEligibleForNotesResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchPostsEligibleForNotesResponse)

Response for searchEligiblePosts

#### Defined in

[community\_notes/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/models.ts#L18)

***

### EvaluateRequest

Ƭ **EvaluateRequest**: [`EvaluateNoteRequest`](/xdks/typescript/reference/interfaces/Schemas.EvaluateNoteRequest)

Request for evaluate

#### Defined in

[community\_notes/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/models.ts#L24)

***

### EvaluateResponse

Ƭ **EvaluateResponse**: [`EvaluateNoteResponse`](/xdks/typescript/reference/interfaces/Schemas.EvaluateNoteResponse)

Response for evaluate

#### Defined in

[community\_notes/models.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/models.ts#L30)

***

### SearchWrittenResponse

Ƭ **SearchWrittenResponse**: [`Get2NotesSearchNotesWrittenResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchNotesWrittenResponse)

Response for searchWritten

#### Defined in

[community\_notes/models.ts:36](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/models.ts#L36)

***

### DeleteResponse

Ƭ **DeleteResponse**: [`DeleteNoteResponse`](/xdks/typescript/reference/interfaces/Schemas.DeleteNoteResponse)

Response for delete

#### Defined in

[community\_notes/models.ts:42](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/models.ts#L42)

***

### CreateRequest

Ƭ **CreateRequest**: [`CreateNoteRequest`](/xdks/typescript/reference/interfaces/Schemas.CreateNoteRequest)

Request for create

#### Defined in

[community\_notes/models.ts:48](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/models.ts#L48)

***

### CreateResponse

Ƭ **CreateResponse**: [`CreateNoteResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateNoteResponse)

Response for create

#### Defined in

[community\_notes/models.ts:54](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/community_notes/models.ts#L54)


# Namespace: Compliance
Source: https://docs.x.com/xdks/typescript/reference/modules/Compliance

Reference for the Compliance module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### GetJobsByIdResponse

Ƭ **GetJobsByIdResponse**: [`Get2ComplianceJobsIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsIdResponse)

Response for getJobsById

#### Defined in

[compliance/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/compliance/models.ts#L18)

***

### GetJobsResponse

Ƭ **GetJobsResponse**: [`Get2ComplianceJobsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsResponse)

Response for getJobs

#### Defined in

[compliance/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/compliance/models.ts#L24)

***

### CreateJobsRequest

Ƭ **CreateJobsRequest**: [`CreateComplianceJobRequest`](/xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobRequest)

Request for createJobs

#### Defined in

[compliance/models.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/compliance/models.ts#L30)

***

### CreateJobsResponse

Ƭ **CreateJobsResponse**: [`CreateComplianceJobResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobResponse)

Response for createJobs

#### Defined in

[compliance/models.ts:36](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/compliance/models.ts#L36)


# Namespace: Connections
Source: https://docs.x.com/xdks/typescript/reference/modules/Connections

Reference for the Connections module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### GetConnectionHistoryResponse

Ƭ **GetConnectionHistoryResponse**: [`Get2ConnectionsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ConnectionsResponse)

Response for getConnectionHistory

#### Defined in

[connections/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/connections/models.ts#L18)

***

### DeleteAllResponse

Ƭ **DeleteAllResponse**: [`KillAllConnectionsResponse`](/xdks/typescript/reference/interfaces/Schemas.KillAllConnectionsResponse)

Response for deleteAll

#### Defined in

[connections/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/connections/models.ts#L24)


# Namespace: DirectMessages
Source: https://docs.x.com/xdks/typescript/reference/modules/DirectMessages

Reference for the DirectMessages module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### CreateByConversationIdRequest

Ƭ **CreateByConversationIdRequest**: [`CreateMessageRequest`](/xdks/typescript/reference/modules/Schemas#createmessagerequest)

Request for createByConversationId

#### Defined in

[direct\_messages/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/models.ts#L18)

***

### CreateByConversationIdResponse

Ƭ **CreateByConversationIdResponse**: [`CreateDmEventResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse)

Response for createByConversationId

#### Defined in

[direct\_messages/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/models.ts#L24)

***

### GetEventsByConversationIdResponse

Ƭ **GetEventsByConversationIdResponse**: [`Get2DmConversationsIdDmEventsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsIdDmEventsResponse)

Response for getEventsByConversationId

#### Defined in

[direct\_messages/models.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/models.ts#L30)

***

### CreateConversationRequest

Ƭ **CreateConversationRequest**: [`CreateDmConversationRequest`](/xdks/typescript/reference/interfaces/Schemas.CreateDmConversationRequest)

Request for createConversation

#### Defined in

[direct\_messages/models.ts:36](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/models.ts#L36)

***

### CreateConversationResponse

Ƭ **CreateConversationResponse**: [`CreateDmEventResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse)

Response for createConversation

#### Defined in

[direct\_messages/models.ts:42](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/models.ts#L42)

***

### GetEventsByParticipantIdResponse

Ƭ **GetEventsByParticipantIdResponse**: [`Get2DmConversationsWithParticipantIdDmEventsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsWithParticipantIdDmEventsResponse)

Response for getEventsByParticipantId

#### Defined in

[direct\_messages/models.ts:48](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/models.ts#L48)

***

### GetEventsResponse

Ƭ **GetEventsResponse**: [`Get2DmEventsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2DmEventsResponse)

Response for getEvents

#### Defined in

[direct\_messages/models.ts:54](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/models.ts#L54)

***

### GetEventsByIdResponse

Ƭ **GetEventsByIdResponse**: [`Get2DmEventsEventIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2DmEventsEventIdResponse)

Response for getEventsById

#### Defined in

[direct\_messages/models.ts:60](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/models.ts#L60)

***

### DeleteEventsResponse

Ƭ **DeleteEventsResponse**: [`DeleteDmResponse`](/xdks/typescript/reference/interfaces/Schemas.DeleteDmResponse)

Response for deleteEvents

#### Defined in

[direct\_messages/models.ts:66](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/models.ts#L66)

***

### CreateByParticipantIdRequest

Ƭ **CreateByParticipantIdRequest**: [`CreateMessageRequest`](/xdks/typescript/reference/modules/Schemas#createmessagerequest)

Request for createByParticipantId

#### Defined in

[direct\_messages/models.ts:72](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/models.ts#L72)

***

### CreateByParticipantIdResponse

Ƭ **CreateByParticipantIdResponse**: [`CreateDmEventResponse`](/xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse)

Response for createByParticipantId

#### Defined in

[direct\_messages/models.ts:78](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/direct_messages/models.ts#L78)


# Namespace: General
Source: https://docs.x.com/xdks/typescript/reference/modules/General

Reference for the General module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### GetOpenApiSpecResponse

Ƭ **GetOpenApiSpecResponse**: `Record`\<`string`, `any`>

Response for getOpenApiSpec

#### Defined in

[general/models.ts:19](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/general/models.ts#L19)


# Namespace: Lists
Source: https://docs.x.com/xdks/typescript/reference/modules/Lists

Reference for the Lists module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### GetFollowersResponse

Ƭ **GetFollowersResponse**: [`Get2ListsIdFollowersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdFollowersResponse)

Response for getFollowers

#### Defined in

[lists/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/models.ts#L18)

***

### CreateRequest

Ƭ **CreateRequest**: [`ListCreateRequest`](/xdks/typescript/reference/interfaces/Schemas.ListCreateRequest)

Request for create

#### Defined in

[lists/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/models.ts#L24)

***

### CreateResponse

Ƭ **CreateResponse**: [`ListCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.ListCreateResponse)

Response for create

#### Defined in

[lists/models.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/models.ts#L30)

***

### GetMembersResponse

Ƭ **GetMembersResponse**: [`Get2ListsIdMembersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdMembersResponse)

Response for getMembers

#### Defined in

[lists/models.ts:36](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/models.ts#L36)

***

### AddMemberRequest

Ƭ **AddMemberRequest**: [`ListAddUserRequest`](/xdks/typescript/reference/interfaces/Schemas.ListAddUserRequest)

Request for addMember

#### Defined in

[lists/models.ts:42](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/models.ts#L42)

***

### AddMemberResponse

Ƭ **AddMemberResponse**: [`ListMutateResponse`](/xdks/typescript/reference/interfaces/Schemas.ListMutateResponse)

Response for addMember

#### Defined in

[lists/models.ts:48](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/models.ts#L48)

***

### GetPostsResponse

Ƭ **GetPostsResponse**: [`Get2ListsIdTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdTweetsResponse)

Response for getPosts

#### Defined in

[lists/models.ts:54](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/models.ts#L54)

***

### RemoveMemberByUserIdResponse

Ƭ **RemoveMemberByUserIdResponse**: [`ListMutateResponse`](/xdks/typescript/reference/interfaces/Schemas.ListMutateResponse)

Response for removeMemberByUserId

#### Defined in

[lists/models.ts:60](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/models.ts#L60)

***

### GetByIdResponse

Ƭ **GetByIdResponse**: [`Get2ListsIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2ListsIdResponse)

Response for getById

#### Defined in

[lists/models.ts:66](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/models.ts#L66)

***

### UpdateRequest

Ƭ **UpdateRequest**: [`ListUpdateRequest`](/xdks/typescript/reference/interfaces/Schemas.ListUpdateRequest)

Request for update

#### Defined in

[lists/models.ts:72](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/models.ts#L72)

***

### UpdateResponse

Ƭ **UpdateResponse**: [`ListUpdateResponse`](/xdks/typescript/reference/interfaces/Schemas.ListUpdateResponse)

Response for update

#### Defined in

[lists/models.ts:78](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/models.ts#L78)

***

### DeleteResponse

Ƭ **DeleteResponse**: [`ListDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.ListDeleteResponse)

Response for delete

#### Defined in

[lists/models.ts:84](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/lists/models.ts#L84)


# Namespace: Media
Source: https://docs.x.com/xdks/typescript/reference/modules/Media

Reference for the Media module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

zeUploadResponse]\(/xdks/typescript/reference/modules/Media#finalizeuploadresponse)

* [InitializeUploadRequest](/xdks/typescript/reference/modules/Media#initializeuploadrequest)
* [InitializeUploadResponse](/xdks/typescript/reference/modules/Media#initializeuploadresponse)
* [CreateSubtitlesRequest](/xdks/typescript/reference/modules/Media#createsubtitlesrequest)
* [CreateSubtitlesResponse](/xdks/typescript/reference/modules/Media#createsubtitlesresponse)
* [DeleteSubtitlesRequest](/xdks/typescript/reference/modules/Media#deletesubtitlesrequest)
* [DeleteSubtitlesResponse](/xdks/typescript/reference/modules/Media#deletesubtitlesresponse)

## Type Aliases

### GetByKeyResponse

Ƭ **GetByKeyResponse**: [`Get2MediaMediaKeyResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2MediaMediaKeyResponse)

Response for getByKey

#### Defined in

[media/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L18)

***

### GetUploadStatusResponse

Ƭ **GetUploadStatusResponse**: [`MediaUploadResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)

Response for getUploadStatus

#### Defined in

[media/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L24)

***

### UploadRequest

Ƭ **UploadRequest**: [`MediaUploadRequestOneShot`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadRequestOneShot)

Request for upload

#### Defined in

[media/models.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L30)

***

### UploadResponse

Ƭ **UploadResponse**: [`MediaUploadResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)

Response for upload

#### Defined in

[media/models.ts:36](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L36)

***

### GetAnalyticsResponse

Ƭ **GetAnalyticsResponse**: [`MediaAnalytics`](/xdks/typescript/reference/interfaces/Schemas.MediaAnalytics)

Response for getAnalytics

#### Defined in

[media/models.ts:42](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L42)

***

### AppendUploadRequest

Ƭ **AppendUploadRequest**: [`MediaUploadAppendRequest`](/xdks/typescript/reference/modules/Schemas#mediauploadappendrequest)

Request for appendUpload

#### Defined in

[media/models.ts:48](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L48)

***

### AppendUploadResponse

Ƭ **AppendUploadResponse**: [`MediaUploadAppendResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadAppendResponse)

Response for appendUpload

#### Defined in

[media/models.ts:54](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L54)

***

### GetByKeysResponse

Ƭ **GetByKeysResponse**: [`Get2MediaResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2MediaResponse)

Response for getByKeys

#### Defined in

[media/models.ts:60](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L60)

***

### CreateMetadataRequest

Ƭ **CreateMetadataRequest**: [`MetadataCreateRequest`](/xdks/typescript/reference/interfaces/Schemas.MetadataCreateRequest)

Request for createMetadata

#### Defined in

[media/models.ts:66](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L66)

***

### CreateMetadataResponse

Ƭ **CreateMetadataResponse**: [`MetadataCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.MetadataCreateResponse)

Response for createMetadata

#### Defined in

[media/models.ts:72](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L72)

***

### FinalizeUploadResponse

Ƭ **FinalizeUploadResponse**: [`MediaUploadResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)

Response for finalizeUpload

#### Defined in

[media/models.ts:78](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L78)

***

### InitializeUploadRequest

Ƭ **InitializeUploadRequest**: [`MediaUploadConfigRequest`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadConfigRequest)

Request for initializeUpload

#### Defined in

[media/models.ts:84](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L84)

***

### InitializeUploadResponse

Ƭ **InitializeUploadResponse**: [`MediaUploadResponse`](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)

Response for initializeUpload

#### Defined in

[media/models.ts:90](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L90)

***

### CreateSubtitlesRequest

Ƭ **CreateSubtitlesRequest**: [`SubtitlesCreateRequest`](/xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateRequest)

Request for createSubtitles

#### Defined in

[media/models.ts:96](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L96)

***

### CreateSubtitlesResponse

Ƭ **CreateSubtitlesResponse**: [`SubtitlesCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateResponse)

Response for createSubtitles

#### Defined in

[media/models.ts:102](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L102)

***

### DeleteSubtitlesRequest

Ƭ **DeleteSubtitlesRequest**: [`SubtitlesDeleteRequest`](/xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteRequest)

Request for deleteSubtitles

#### Defined in

[media/models.ts:108](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L108)

***

### DeleteSubtitlesResponse

Ƭ **DeleteSubtitlesResponse**: [`SubtitlesDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteResponse)

Response for deleteSubtitles

#### Defined in

[media/models.ts:114](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/media/models.ts#L114)


# Namespace: News
Source: https://docs.x.com/xdks/typescript/reference/modules/News

Reference for the News module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### GetResponse

Ƭ **GetResponse**: [`Get2NewsIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2NewsIdResponse)

Response for get

#### Defined in

[news/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/news/models.ts#L18)

***

### SearchResponse

Ƭ **SearchResponse**: [`Get2NewsSearchResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2NewsSearchResponse)

Response for search

#### Defined in

[news/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/news/models.ts#L24)


# Namespace: Posts
Source: https://docs.x.com/xdks/typescript/reference/modules/Posts

Reference for the Posts module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### GetInsights28hrResponse

Ƭ **GetInsights28hrResponse**: [`Get2Insights28hrResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2Insights28hrResponse)

Response for getInsights28hr

#### Defined in

[posts/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L18)

***

### GetAnalyticsResponse

Ƭ **GetAnalyticsResponse**: [`Analytics`](/xdks/typescript/reference/interfaces/Schemas.Analytics)

Response for getAnalytics

#### Defined in

[posts/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L24)

***

### GetRepostsResponse

Ƭ **GetRepostsResponse**: [`Get2TweetsIdRetweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetsResponse)

Response for getReposts

#### Defined in

[posts/models.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L30)

***

### SearchRecentResponse

Ƭ **SearchRecentResponse**: [`Get2TweetsSearchRecentResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchRecentResponse)

Response for searchRecent

#### Defined in

[posts/models.ts:36](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L36)

***

### SearchAllResponse

Ƭ **SearchAllResponse**: [`Get2TweetsSearchAllResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchAllResponse)

Response for searchAll

#### Defined in

[posts/models.ts:42](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L42)

***

### GetByIdsResponse

Ƭ **GetByIdsResponse**: [`Get2TweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsResponse)

Response for getByIds

#### Defined in

[posts/models.ts:48](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L48)

***

### CreateRequest

Ƭ **CreateRequest**: [`TweetCreateRequest`](/xdks/typescript/reference/interfaces/Schemas.TweetCreateRequest)

Request for create

#### Defined in

[posts/models.ts:54](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L54)

***

### CreateResponse

Ƭ **CreateResponse**: [`TweetCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.TweetCreateResponse)

Response for create

#### Defined in

[posts/models.ts:60](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L60)

***

### GetQuotedResponse

Ƭ **GetQuotedResponse**: [`Get2TweetsIdQuoteTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdQuoteTweetsResponse)

Response for getQuoted

#### Defined in

[posts/models.ts:66](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L66)

***

### GetCountsRecentResponse

Ƭ **GetCountsRecentResponse**: [`Get2TweetsCountsRecentResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsRecentResponse)

Response for getCountsRecent

#### Defined in

[posts/models.ts:72](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L72)

***

### HideReplyRequest

Ƭ **HideReplyRequest**: [`TweetHideRequest`](/xdks/typescript/reference/interfaces/Schemas.TweetHideRequest)

Request for hideReply

#### Defined in

[posts/models.ts:78](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L78)

***

### HideReplyResponse

Ƭ **HideReplyResponse**: [`TweetHideResponse`](/xdks/typescript/reference/interfaces/Schemas.TweetHideResponse)

Response for hideReply

#### Defined in

[posts/models.ts:84](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L84)

***

### GetInsightsHistoricalResponse

Ƭ **GetInsightsHistoricalResponse**: [`Get2InsightsHistoricalResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2InsightsHistoricalResponse)

Response for getInsightsHistorical

#### Defined in

[posts/models.ts:90](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L90)

***

### GetCountsAllResponse

Ƭ **GetCountsAllResponse**: [`Get2TweetsCountsAllResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsAllResponse)

Response for getCountsAll

#### Defined in

[posts/models.ts:96](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L96)

***

### GetByIdResponse

Ƭ **GetByIdResponse**: [`Get2TweetsIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdResponse)

Response for getById

#### Defined in

[posts/models.ts:102](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L102)

***

### DeleteResponse

Ƭ **DeleteResponse**: [`TweetDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.TweetDeleteResponse)

Response for delete

#### Defined in

[posts/models.ts:108](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L108)

***

### GetLikingUsersResponse

Ƭ **GetLikingUsersResponse**: [`Get2TweetsIdLikingUsersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdLikingUsersResponse)

Response for getLikingUsers

#### Defined in

[posts/models.ts:114](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L114)

***

### GetRepostedByResponse

Ƭ **GetRepostedByResponse**: [`Get2TweetsIdRetweetedByResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetedByResponse)

Response for getRepostedBy

#### Defined in

[posts/models.ts:120](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/posts/models.ts#L120)


# Namespace: Schemas
Source: https://docs.x.com/xdks/typescript/reference/modules/Schemas

Reference for the Schemas module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

zedTrendsResponse]\(/xdks/typescript/reference/interfaces/Schemas.Get2UsersPersonalizedTrendsResponse)

* [Get2UsersRepostsOfMeResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersRepostsOfMeResponse)
* [Get2UsersResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersResponse)
* [Get2UsersSearchResponse](/xdks/typescript/reference/interfaces/Schemas.Get2UsersSearchResponse)
* [Get2WebhooksResponse](/xdks/typescript/reference/interfaces/Schemas.Get2WebhooksResponse)
* [HashtagFields](/xdks/typescript/reference/interfaces/Schemas.HashtagFields)
* [KillAllConnectionsResponse](/xdks/typescript/reference/interfaces/Schemas.KillAllConnectionsResponse)
* [LikeComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.LikeComplianceSchema)
* [LikeWithTweetAuthor](/xdks/typescript/reference/interfaces/Schemas.LikeWithTweetAuthor)
* [List](/xdks/typescript/reference/interfaces/Schemas.List)
* [ListAddUserRequest](/xdks/typescript/reference/interfaces/Schemas.ListAddUserRequest)
* [ListCreateRequest](/xdks/typescript/reference/interfaces/Schemas.ListCreateRequest)
* [ListCreateResponse](/xdks/typescript/reference/interfaces/Schemas.ListCreateResponse)
* [ListDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.ListDeleteResponse)
* [ListFollowedRequest](/xdks/typescript/reference/interfaces/Schemas.ListFollowedRequest)
* [ListFollowedResponse](/xdks/typescript/reference/interfaces/Schemas.ListFollowedResponse)
* [ListMutateResponse](/xdks/typescript/reference/interfaces/Schemas.ListMutateResponse)
* [ListPinnedRequest](/xdks/typescript/reference/interfaces/Schemas.ListPinnedRequest)
* [ListPinnedResponse](/xdks/typescript/reference/interfaces/Schemas.ListPinnedResponse)
* [ListUnpinResponse](/xdks/typescript/reference/interfaces/Schemas.ListUnpinResponse)
* [ListUpdateRequest](/xdks/typescript/reference/interfaces/Schemas.ListUpdateRequest)
* [ListUpdateResponse](/xdks/typescript/reference/interfaces/Schemas.ListUpdateResponse)
* [ManagementInfo](/xdks/typescript/reference/interfaces/Schemas.ManagementInfo)
* [Media](/xdks/typescript/reference/interfaces/Schemas.Media)
* [MediaAnalytics](/xdks/typescript/reference/interfaces/Schemas.MediaAnalytics)
* [MediaMetrics](/xdks/typescript/reference/interfaces/Schemas.MediaMetrics)
* [MediaTimestampedMetrics](/xdks/typescript/reference/interfaces/Schemas.MediaTimestampedMetrics)
* [MediaUploadAppendResponse](/xdks/typescript/reference/interfaces/Schemas.MediaUploadAppendResponse)
* [MediaUploadConfigRequest](/xdks/typescript/reference/interfaces/Schemas.MediaUploadConfigRequest)
* [MediaUploadRequestOneShot](/xdks/typescript/reference/interfaces/Schemas.MediaUploadRequestOneShot)
* [MediaUploadResponse](/xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse)
* [MentionFields](/xdks/typescript/reference/interfaces/Schemas.MentionFields)
* [MetadataCreateRequest](/xdks/typescript/reference/interfaces/Schemas.MetadataCreateRequest)
* [MetadataCreateResponse](/xdks/typescript/reference/interfaces/Schemas.MetadataCreateResponse)
* [Metrics](/xdks/typescript/reference/interfaces/Schemas.Metrics)
* [MuteUserMutationResponse](/xdks/typescript/reference/interfaces/Schemas.MuteUserMutationResponse)
* [MuteUserRequest](/xdks/typescript/reference/interfaces/Schemas.MuteUserRequest)
* [News](/xdks/typescript/reference/interfaces/Schemas.News)
* [NewsActivityResponsePayload](/xdks/typescript/reference/interfaces/Schemas.NewsActivityResponsePayload)
* [Note](/xdks/typescript/reference/interfaces/Schemas.Note)
* [NoteInfo](/xdks/typescript/reference/interfaces/Schemas.NoteInfo)
* [NoteTestResult](/xdks/typescript/reference/interfaces/Schemas.NoteTestResult)
* [PersonalizedTrend](/xdks/typescript/reference/interfaces/Schemas.PersonalizedTrend)
* [Place](/xdks/typescript/reference/interfaces/Schemas.Place)
* [PlaidAccount](/xdks/typescript/reference/interfaces/Schemas.PlaidAccount)
* [PlaidAccountContact](/xdks/typescript/reference/interfaces/Schemas.PlaidAccountContact)
* [PlaidAccountPaymentNetwork](/xdks/typescript/reference/interfaces/Schemas.PlaidAccountPaymentNetwork)
* [PlaidAccountTransaction](/xdks/typescript/reference/interfaces/Schemas.PlaidAccountTransaction)
* [PlaidAddress](/xdks/typescript/reference/interfaces/Schemas.PlaidAddress)
* [PlaidCurrency](/xdks/typescript/reference/interfaces/Schemas.PlaidCurrency)
* [PlaidCustomer](/xdks/typescript/reference/interfaces/Schemas.PlaidCustomer)
* [PlaidName](/xdks/typescript/reference/interfaces/Schemas.PlaidName)
* [PlaidTelephone](/xdks/typescript/reference/interfaces/Schemas.PlaidTelephone)
* [Point](/xdks/typescript/reference/interfaces/Schemas.Point)
* [Poll](/xdks/typescript/reference/interfaces/Schemas.Poll)
* [PollOption](/xdks/typescript/reference/interfaces/Schemas.PollOption)
* [PreviewImage](/xdks/typescript/reference/interfaces/Schemas.PreviewImage)
* [Problem](/xdks/typescript/reference/interfaces/Schemas.Problem)
* [ProcessingInfo](/xdks/typescript/reference/interfaces/Schemas.ProcessingInfo)
* [ProfileUpdateActivityResponsePayload](/xdks/typescript/reference/interfaces/Schemas.ProfileUpdateActivityResponsePayload)
* [ReplayJobCreateResponse](/xdks/typescript/reference/interfaces/Schemas.ReplayJobCreateResponse)
* [Rule](/xdks/typescript/reference/interfaces/Schemas.Rule)
* [RuleNoId](/xdks/typescript/reference/interfaces/Schemas.RuleNoId)
* [RulesCount](/xdks/typescript/reference/interfaces/Schemas.RulesCount)
* [RulesLookupResponse](/xdks/typescript/reference/interfaces/Schemas.RulesLookupResponse)
* [RulesResponseMetadata](/xdks/typescript/reference/interfaces/Schemas.RulesResponseMetadata)
* [SearchCount](/xdks/typescript/reference/interfaces/Schemas.SearchCount)
* [SensitiveMediaWarning](/xdks/typescript/reference/interfaces/Schemas.SensitiveMediaWarning)
* [SharedInfo](/xdks/typescript/reference/interfaces/Schemas.SharedInfo)
* [Space](/xdks/typescript/reference/interfaces/Schemas.Space)
* [Sticker](/xdks/typescript/reference/interfaces/Schemas.Sticker)
* [StickerInfo](/xdks/typescript/reference/interfaces/Schemas.StickerInfo)
* [StreamingLikeResponseV2](/xdks/typescript/reference/interfaces/Schemas.StreamingLikeResponseV2)
* [StreamingTweetResponse](/xdks/typescript/reference/interfaces/Schemas.StreamingTweetResponse)
* [SubscriptionsCountGetResponse](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsCountGetResponse)
* [SubscriptionsCreateResponse](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsCreateResponse)
* [SubscriptionsDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsDeleteResponse)
* [SubscriptionsGetResponse](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsGetResponse)
* [SubscriptionsListGetResponse](/xdks/typescript/reference/interfaces/Schemas.SubscriptionsListGetResponse)
* [Subtitles](/xdks/typescript/reference/interfaces/Schemas.Subtitles)
* [SubtitlesCreateRequest](/xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateRequest)
* [SubtitlesCreateResponse](/xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateResponse)
* [SubtitlesDeleteRequest](/xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteRequest)
* [SubtitlesDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteResponse)
* [TimestampedMetrics](/xdks/typescript/reference/interfaces/Schemas.TimestampedMetrics)
* [Topic](/xdks/typescript/reference/interfaces/Schemas.Topic)
* [Trend](/xdks/typescript/reference/interfaces/Schemas.Trend)
* [Tweet](/xdks/typescript/reference/interfaces/Schemas.Tweet)
* [TweetComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetComplianceSchema)
* [TweetCreateRequest](/xdks/typescript/reference/interfaces/Schemas.TweetCreateRequest)
* [TweetCreateResponse](/xdks/typescript/reference/interfaces/Schemas.TweetCreateResponse)
* [TweetDeleteComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetDeleteComplianceSchema)
* [TweetDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.TweetDeleteResponse)
* [TweetDropComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetDropComplianceSchema)
* [TweetEditComplianceObjectSchema](/xdks/typescript/reference/interfaces/Schemas.TweetEditComplianceObjectSchema)
* [TweetEditComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetEditComplianceSchema)
* [TweetHideRequest](/xdks/typescript/reference/interfaces/Schemas.TweetHideRequest)
* [TweetHideResponse](/xdks/typescript/reference/interfaces/Schemas.TweetHideResponse)
* [TweetNotice](/xdks/typescript/reference/interfaces/Schemas.TweetNotice)
* [TweetNoticeSchema](/xdks/typescript/reference/interfaces/Schemas.TweetNoticeSchema)
* [TweetTakedownComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetTakedownComplianceSchema)
* [TweetUndropComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetUndropComplianceSchema)
* [TweetUnviewable](/xdks/typescript/reference/interfaces/Schemas.TweetUnviewable)
* [TweetUnviewableSchema](/xdks/typescript/reference/interfaces/Schemas.TweetUnviewableSchema)
* [TweetWithheld](/xdks/typescript/reference/interfaces/Schemas.TweetWithheld)
* [TweetWithheldComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.TweetWithheldComplianceSchema)
* [UnlikeComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UnlikeComplianceSchema)
* [UploadSource](/xdks/typescript/reference/interfaces/Schemas.UploadSource)
* [UrlFields](/xdks/typescript/reference/interfaces/Schemas.UrlFields)
* [UrlImage](/xdks/typescript/reference/interfaces/Schemas.UrlImage)
* [Usage](/xdks/typescript/reference/interfaces/Schemas.Usage)
* [UsageFields](/xdks/typescript/reference/interfaces/Schemas.UsageFields)
* [User](/xdks/typescript/reference/interfaces/Schemas.User)
* [UserComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserComplianceSchema)
* [UserDeleteComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserDeleteComplianceSchema)
* [UserProfileModificationComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserProfileModificationComplianceSchema)
* [UserProfileModificationObjectSchema](/xdks/typescript/reference/interfaces/Schemas.UserProfileModificationObjectSchema)
* [UserProtectComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserProtectComplianceSchema)
* [UserScrubGeoObjectSchema](/xdks/typescript/reference/interfaces/Schemas.UserScrubGeoObjectSchema)
* [UserScrubGeoSchema](/xdks/typescript/reference/interfaces/Schemas.UserScrubGeoSchema)
* [UsersDMBlockCreateResponse](/xdks/typescript/reference/interfaces/Schemas.UsersDMBlockCreateResponse)
* [UsersDMUnBlockCreateResponse](/xdks/typescript/reference/interfaces/Schemas.UsersDMUnBlockCreateResponse)
* [UsersFollowingCreateRequest](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateRequest)
* [UsersFollowingCreateResponse](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateResponse)
* [UsersFollowingDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingDeleteResponse)
* [UsersLikesCreateRequest](/xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateRequest)
* [UsersLikesCreateResponse](/xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateResponse)
* [UsersLikesDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.UsersLikesDeleteResponse)
* [UsersRetweetsCreateRequest](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateRequest)
* [UsersRetweetsCreateResponse](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateResponse)
* [UsersRetweetsDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsDeleteResponse)
* [UserSuspendComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserSuspendComplianceSchema)
* [UserTakedownComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserTakedownComplianceSchema)
* [UserUndeleteComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserUndeleteComplianceSchema)
* [UserUnprotectComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserUnprotectComplianceSchema)
* [UserUnsuspendComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserUnsuspendComplianceSchema)
* [UserWithheld](/xdks/typescript/reference/interfaces/Schemas.UserWithheld)
* [UserWithheldComplianceSchema](/xdks/typescript/reference/interfaces/Schemas.UserWithheldComplianceSchema)
* [Variant](/xdks/typescript/reference/interfaces/Schemas.Variant)
* [WebhookConfig](/xdks/typescript/reference/interfaces/Schemas.WebhookConfig)
* [WebhookConfigCreateRequest](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateRequest)
* [WebhookConfigCreateResponse](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateResponse)
* [WebhookConfigDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigDeleteResponse)
* [WebhookConfigPutResponse](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigPutResponse)
* [WebhookLinksCreateResponse](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksCreateResponse)
* [WebhookLinksDeleteResponse](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksDeleteResponse)
* [WebhookLinksGetResponse](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksGetResponse)
* [WebhookReplayCreateRequest](/xdks/typescript/reference/interfaces/Schemas.WebhookReplayCreateRequest)

### Type Aliases

* [ActivityEventId](/xdks/typescript/reference/modules/Schemas#activityeventid)
* [ActivityStreamingResponsePayload](/xdks/typescript/reference/modules/Schemas#activitystreamingresponsepayload)
* [ActivitySubscriptionId](/xdks/typescript/reference/modules/Schemas#activitysubscriptionid)
* [AddOrDeleteRulesRequest](/xdks/typescript/reference/modules/Schemas#addordeleterulesrequest)
* [Aggregate](/xdks/typescript/reference/modules/Schemas#aggregate)
* [AllProjectClientApps](/xdks/typescript/reference/modules/Schemas#allprojectclientapps)
* [AnimatedGif](/xdks/typescript/reference/modules/Schemas#animatedgif)
* [BookmarkFolderId](/xdks/typescript/reference/modules/Schemas#bookmarkfolderid)
* [CashtagEntity](/xdks/typescript/reference/modules/Schemas#cashtagentity)
* [ClientAppId](/xdks/typescript/reference/modules/Schemas#clientappid)
* [ClientDisconnectedProblem](/xdks/typescript/reference/modules/Schemas#clientdisconnectedproblem)
* [ClientForbiddenProblem](/xdks/typescript/reference/modules/Schemas#clientforbiddenproblem)
* [CommunityId](/xdks/typescript/reference/modules/Schemas#communityid)
* [ComplianceJobName](/xdks/typescript/reference/modules/Schemas#compliancejobname)
* [ComplianceJobStatus](/xdks/typescript/reference/modules/Schemas#compliancejobstatus)
* [ComplianceJobType](/xdks/typescript/reference/modules/Schemas#compliancejobtype)
* [ConflictProblem](/xdks/typescript/reference/modules/Schemas#conflictproblem)
* [ConnectionExceptionProblem](/xdks/typescript/reference/modules/Schemas#connectionexceptionproblem)
* [CountryCode](/xdks/typescript/reference/modules/Schemas#countrycode)
* [CreatedAt](/xdks/typescript/reference/modules/Schemas#createdat)
* [CreateMessageRequest](/xdks/typescript/reference/modules/Schemas#createmessagerequest)
* [DisallowedResourceProblem](/xdks/typescript/reference/modules/Schemas#disallowedresourceproblem)
* [DisplayTextRange](/xdks/typescript/reference/modules/Schemas#displaytextrange)
* [DmAttachments](/xdks/typescript/reference/modules/Schemas#dmattachments)
* [DmConversationId](/xdks/typescript/reference/modules/Schemas#dmconversationid)
* [DmEventId](/xdks/typescript/reference/modules/Schemas#dmeventid)
* [DmParticipants](/xdks/typescript/reference/modules/Schemas#dmparticipants)
* [DownloadExpiration](/xdks/typescript/reference/modules/Schemas#downloadexpiration)
* [DownloadUrl](/xdks/typescript/reference/modules/Schemas#downloadurl)
* [DuplicateRuleProblem](/xdks/typescript/reference/modules/Schemas#duplicateruleproblem)
* [End](/xdks/typescript/reference/modules/Schemas#end)
* [FieldUnauthorizedProblem](/xdks/typescript/reference/modules/Schemas#fieldunauthorizedproblem)
* [GenericProblem](/xdks/typescript/reference/modules/Schemas#genericproblem)
* [GeoRestrictions](/xdks/typescript/reference/modules/Schemas#georestrictions)
* [HashtagEntity](/xdks/typescript/reference/modules/Schemas#hashtagentity)
* [HttpStatusCode](/xdks/typescript/reference/modules/Schemas#httpstatuscode)
* [InvalidRequestProblem](/xdks/typescript/reference/modules/Schemas#invalidrequestproblem)
* [InvalidRuleProblem](/xdks/typescript/reference/modules/Schemas#invalidruleproblem)
* [JobId](/xdks/typescript/reference/modules/Schemas#jobid)
* [Keyword](/xdks/typescript/reference/modules/Schemas#keyword)
* [LikeId](/xdks/typescript/reference/modules/Schemas#likeid)
* [LikesComplianceStreamResponse](/xdks/typescript/reference/modules/Schemas#likescompliancestreamresponse)
* [ListId](/xdks/typescript/reference/modules/Schemas#listid)
* [MediaCategory](/xdks/typescript/reference/modules/Schemas#mediacategory)
* [MediaCategoryOneShot](/xdks/typescript/reference/modules/Schemas#mediacategoryoneshot)
* [MediaCategorySubtitles](/xdks/typescript/reference/modules/Schemas#mediacategorysubtitles)
* [MediaHeight](/xdks/typescript/reference/modules/Schemas#mediaheight)
* [MediaId](/xdks/typescript/reference/modules/Schemas#mediaid)
* [MediaKey](/xdks/typescript/reference/modules/Schemas#mediakey)
* [MediaPayloadBinary](/xdks/typescript/reference/modules/Schemas#mediapayloadbinary)
* [MediaPayloadByte](/xdks/typescript/reference/modules/Schemas#mediapayloadbyte)
* [MediaSegments](/xdks/typescript/reference/modules/Schemas#mediasegments)
* [MediaUploadAppendRequest](/xdks/typescript/reference/modules/Schemas#mediauploadappendrequest)
* [MediaWidth](/xdks/typescript/reference/modules/Schemas#mediawidth)
* [MentionEntity](/xdks/typescript/reference/modules/Schemas#mentionentity)
* [MisleadingTags](/xdks/typescript/reference/modules/Schemas#misleadingtags)
* [NewestId](/xdks/typescript/reference/modules/Schemas#newestid)
* [NewsId](/xdks/typescript/reference/modules/Schemas#newsid)
* [NextToken](/xdks/typescript/reference/modules/Schemas#nexttoken)
* [NonCompliantRulesProblem](/xdks/typescript/reference/modules/Schemas#noncompliantrulesproblem)
* [NoteClassification](/xdks/typescript/reference/modules/Schemas#noteclassification)
* [NoteId](/xdks/typescript/reference/modules/Schemas#noteid)
* [NoteRatingStatus](/xdks/typescript/reference/modules/Schemas#noteratingstatus)
* [NoteTweetText](/xdks/typescript/reference/modules/Schemas#notetweettext)
* [Oauth1PermissionsProblem](/xdks/typescript/reference/modules/Schemas#oauth1permissionsproblem)
* [OldestId](/xdks/typescript/reference/modules/Schemas#oldestid)
* [OperationalDisconnectProblem](/xdks/typescript/reference/modules/Schemas#operationaldisconnectproblem)
* [PaginationToken32](/xdks/typescript/reference/modules/Schemas#paginationtoken32)
* [PaginationToken36](/xdks/typescript/reference/modules/Schemas#paginationtoken36)
* [PaginationTokenLong](/xdks/typescript/reference/modules/Schemas#paginationtokenlong)
* [Photo](/xdks/typescript/reference/modules/Schemas#photo)
* [PlaceId](/xdks/typescript/reference/modules/Schemas#placeid)
* [PlaceType](/xdks/typescript/reference/modules/Schemas#placetype)
* [PollId](/xdks/typescript/reference/modules/Schemas#pollid)
* [PollOptionLabel](/xdks/typescript/reference/modules/Schemas#polloptionlabel)
* [Position](/xdks/typescript/reference/modules/Schemas#position)
* [PreviousToken](/xdks/typescript/reference/modules/Schemas#previoustoken)
* [ReplySettings](/xdks/typescript/reference/modules/Schemas#replysettings)
* [ReplySettingsWithVerifiedUsers](/xdks/typescript/reference/modules/Schemas#replysettingswithverifiedusers)
* [ResourceNotFoundProblem](/xdks/typescript/reference/modules/Schemas#resourcenotfoundproblem)
* [ResourceUnauthorizedProblem](/xdks/typescript/reference/modules/Schemas#resourceunauthorizedproblem)
* [ResourceUnavailableProblem](/xdks/typescript/reference/modules/Schemas#resourceunavailableproblem)
* [ResultCount](/xdks/typescript/reference/modules/Schemas#resultcount)
* [RuleId](/xdks/typescript/reference/modules/Schemas#ruleid)
* [RulesCapProblem](/xdks/typescript/reference/modules/Schemas#rulescapproblem)
* [RulesRequestSummary](/xdks/typescript/reference/modules/Schemas#rulesrequestsummary)
* [RuleTag](/xdks/typescript/reference/modules/Schemas#ruletag)
* [RuleValue](/xdks/typescript/reference/modules/Schemas#rulevalue)
* [SpaceId](/xdks/typescript/reference/modules/Schemas#spaceid)
* [Start](/xdks/typescript/reference/modules/Schemas#start)
* [SubscriptionsCreateRequest](/xdks/typescript/reference/modules/Schemas#subscriptionscreaterequest)
* [SubtitleLanguageCode](/xdks/typescript/reference/modules/Schemas#subtitlelanguagecode)
* [TopicId](/xdks/typescript/reference/modules/Schemas#topicid)
* [TweetComplianceData](/xdks/typescript/reference/modules/Schemas#tweetcompliancedata)
* [TweetComplianceStreamResponse](/xdks/typescript/reference/modules/Schemas#tweetcompliancestreamresponse)
* [TweetCount](/xdks/typescript/reference/modules/Schemas#tweetcount)
* [TweetId](/xdks/typescript/reference/modules/Schemas#tweetid)
* [TweetLabelData](/xdks/typescript/reference/modules/Schemas#tweetlabeldata)
* [TweetLabelStreamResponse](/xdks/typescript/reference/modules/Schemas#tweetlabelstreamresponse)
* [TweetText](/xdks/typescript/reference/modules/Schemas#tweettext)
* [UnsupportedAuthenticationProblem](/xdks/typescript/reference/modules/Schemas#unsupportedauthenticationproblem)
* [UploadExpiration](/xdks/typescript/reference/modules/Schemas#uploadexpiration)
* [UploadUrl](/xdks/typescript/reference/modules/Schemas#uploadurl)
* [Url](/xdks/typescript/reference/modules/Schemas#url)
* [UrlEntity](/xdks/typescript/reference/modules/Schemas#urlentity)
* [UrlEntityDm](/xdks/typescript/reference/modules/Schemas#urlentitydm)
* [UsageCapExceededProblem](/xdks/typescript/reference/modules/Schemas#usagecapexceededproblem)
* [UserComplianceData](/xdks/typescript/reference/modules/Schemas#usercompliancedata)
* [UserComplianceStreamResponse](/xdks/typescript/reference/modules/Schemas#usercompliancestreamresponse)
* [UserId](/xdks/typescript/reference/modules/Schemas#userid)
* [UserIdMatchesAuthenticatedUser](/xdks/typescript/reference/modules/Schemas#useridmatchesauthenticateduser)
* [UserName](/xdks/typescript/reference/modules/Schemas#username)
* [UserSearchQueryVnext](/xdks/typescript/reference/modules/Schemas#usersearchqueryvnext)
* [Variants](/xdks/typescript/reference/modules/Schemas#variants)
* [Video](/xdks/typescript/reference/modules/Schemas#video)
* [WebhookConfigId](/xdks/typescript/reference/modules/Schemas#webhookconfigid)

## Type Aliases

### ActivityEventId

Ƭ **ActivityEventId**: `string`

The unique identifier of an Activity event.
\*
\*

#### Defined in

[schemas.ts:19](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L19)

***

### ActivityStreamingResponsePayload

Ƭ **ActivityStreamingResponsePayload**: `any`

Schema type for ActivityStreamingResponsePayload
\*
\*

#### Defined in

[schemas.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L30)

***

### ActivitySubscriptionId

Ƭ **ActivitySubscriptionId**: `string`

#### Defined in

[schemas.ts:65](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L65)

***

### AddOrDeleteRulesRequest

Ƭ **AddOrDeleteRulesRequest**: `any`

Schema type for AddOrDeleteRulesRequest
\*
\*

#### Defined in

[schemas.ts:81](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L81)

***

### Aggregate

Ƭ **Aggregate**: `number`

#### Defined in

[schemas.ts:96](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L96)

***

### AllProjectClientApps

Ƭ **AllProjectClientApps**: [`AppRulesCount`](/xdks/typescript/reference/interfaces/Schemas.AppRulesCount)\[]

#### Defined in

[schemas.ts:106](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L106)

***

### AnimatedGif

Ƭ **AnimatedGif**: `any`

Schema type for AnimatedGif
\*
\*

#### Defined in

[schemas.ts:122](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L122)

***

### BookmarkFolderId

Ƭ **BookmarkFolderId**: `string`

#### Defined in

[schemas.ts:142](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L142)

***

### CashtagEntity

Ƭ **CashtagEntity**: `any`

Schema type for CashtagEntity
\*
\*

#### Defined in

[schemas.ts:163](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L163)

***

### ClientAppId

Ƭ **ClientAppId**: `string`

#### Defined in

[schemas.ts:173](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L173)

***

### ClientDisconnectedProblem

Ƭ **ClientDisconnectedProblem**: `any`

Your client has gone away.
\*
\*

#### Defined in

[schemas.ts:184](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L184)

***

### ClientForbiddenProblem

Ƭ **ClientForbiddenProblem**: `any`

A problem that indicates your client is forbidden from making this request.
\*
\*

#### Defined in

[schemas.ts:190](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L190)

***

### CommunityId

Ƭ **CommunityId**: `string`

#### Defined in

[schemas.ts:200](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L200)

***

### ComplianceJobName

Ƭ **ComplianceJobName**: `string`

#### Defined in

[schemas.ts:210](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L210)

***

### ComplianceJobStatus

Ƭ **ComplianceJobStatus**: `"created"` | `"in_progress"` | `"failed"` | `"complete"` | `"expired"`

#### Defined in

[schemas.ts:215](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L215)

***

### ComplianceJobType

Ƭ **ComplianceJobType**: `"tweets"` | `"users"`

#### Defined in

[schemas.ts:220](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L220)

***

### ConflictProblem

Ƭ **ConflictProblem**: `any`

You cannot create a new job if one is already in progress.
\*
\*

#### Defined in

[schemas.ts:226](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L226)

***

### ConnectionExceptionProblem

Ƭ **ConnectionExceptionProblem**: `any`

A problem that indicates something is wrong with the connection.
\*
\*

#### Defined in

[schemas.ts:237](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L237)

***

### CountryCode

Ƭ **CountryCode**: `string`

#### Defined in

[schemas.ts:262](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L262)

***

### CreatedAt

Ƭ **CreatedAt**: `string`

#### Defined in

[schemas.ts:282](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L282)

***

### CreateMessageRequest

Ƭ **CreateMessageRequest**: `any`

Schema type for CreateMessageRequest
\*
\*

#### Defined in

[schemas.ts:298](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L298)

***

### DisallowedResourceProblem

Ƭ **DisallowedResourceProblem**: `any`

A problem that indicates that the resource requested violates the precepts of this API.
\*
\*

#### Defined in

[schemas.ts:334](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L334)

***

### DisplayTextRange

Ƭ **DisplayTextRange**: `number`\[]

#### Defined in

[schemas.ts:339](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L339)

***

### DmAttachments

Ƭ **DmAttachments**: [`DmMediaAttachment`](/xdks/typescript/reference/interfaces/Schemas.DmMediaAttachment)\[]

#### Defined in

[schemas.ts:344](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L344)

***

### DmConversationId

Ƭ **DmConversationId**: `string`

#### Defined in

[schemas.ts:349](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L349)

***

### DmEventId

Ƭ **DmEventId**: `string`

#### Defined in

[schemas.ts:359](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L359)

***

### DmParticipants

Ƭ **DmParticipants**: [`UserId`](/xdks/typescript/reference/modules/Schemas#userid)\[]

#### Defined in

[schemas.ts:369](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L369)

***

### DownloadExpiration

Ƭ **DownloadExpiration**: `string`

#### Defined in

[schemas.ts:379](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L379)

***

### DownloadUrl

Ƭ **DownloadUrl**: `string`

#### Defined in

[schemas.ts:384](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L384)

***

### DuplicateRuleProblem

Ƭ **DuplicateRuleProblem**: `any`

The rule you have submitted is a duplicate.
\*
\*

#### Defined in

[schemas.ts:390](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L390)

***

### End

Ƭ **End**: `string`

#### Defined in

[schemas.ts:395](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L395)

***

### FieldUnauthorizedProblem

Ƭ **FieldUnauthorizedProblem**: `any`

A problem that indicates that you are not allowed to see a particular field on a Tweet, User, etc.
\*
\*

#### Defined in

[schemas.ts:436](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L436)

***

### GenericProblem

Ƭ **GenericProblem**: `any`

A generic problem with no additional information beyond that provided by the HTTP status code.
\*
\*

#### Defined in

[schemas.ts:462](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L462)

***

### GeoRestrictions

Ƭ **GeoRestrictions**: `any`

Schema type for GeoRestrictions
\*
\*

#### Defined in

[schemas.ts:473](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L473)

***

### HashtagEntity

Ƭ **HashtagEntity**: `any`

Schema type for HashtagEntity
\*
\*

#### Defined in

[schemas.ts:874](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L874)

***

### HttpStatusCode

Ƭ **HttpStatusCode**: `number`

#### Defined in

[schemas.ts:884](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L884)

***

### InvalidRequestProblem

Ƭ **InvalidRequestProblem**: `any`

A problem that indicates this request is invalid.
\*
\*

#### Defined in

[schemas.ts:890](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L890)

***

### InvalidRuleProblem

Ƭ **InvalidRuleProblem**: `any`

The rule you have submitted is invalid.
\*
\*

#### Defined in

[schemas.ts:896](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L896)

***

### JobId

Ƭ **JobId**: `string`

#### Defined in

[schemas.ts:901](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L901)

***

### Keyword

Ƭ **Keyword**: `string`

#### Defined in

[schemas.ts:906](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L906)

***

### LikeId

Ƭ **LikeId**: `string`

#### Defined in

[schemas.ts:921](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L921)

***

### LikesComplianceStreamResponse

Ƭ **LikesComplianceStreamResponse**: `any`

Likes compliance stream events.
\*
\*

#### Defined in

[schemas.ts:927](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L927)

***

### ListId

Ƭ **ListId**: `string`

#### Defined in

[schemas.ts:972](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L972)

***

### MediaCategory

Ƭ **MediaCategory**: `"amplify_video"` | `"tweet_gif"` | `"tweet_image"` | `"tweet_video"` | `"dm_gif"` | `"dm_image"` | `"dm_video"` | `"subtitles"`

#### Defined in

[schemas.ts:1022](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1022)

***

### MediaCategoryOneShot

Ƭ **MediaCategoryOneShot**: `"tweet_image"` | `"dm_image"` | `"subtitles"`

#### Defined in

[schemas.ts:1027](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1027)

***

### MediaCategorySubtitles

Ƭ **MediaCategorySubtitles**: `"AmplifyVideo"` | `"TweetVideo"`

#### Defined in

[schemas.ts:1032](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1032)

***

### MediaHeight

Ƭ **MediaHeight**: `number`

#### Defined in

[schemas.ts:1037](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1037)

***

### MediaId

Ƭ **MediaId**: `string`

#### Defined in

[schemas.ts:1042](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1042)

***

### MediaKey

Ƭ **MediaKey**: `string`

#### Defined in

[schemas.ts:1047](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1047)

***

### MediaPayloadBinary

Ƭ **MediaPayloadBinary**: `string`

#### Defined in

[schemas.ts:1057](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1057)

***

### MediaPayloadByte

Ƭ **MediaPayloadByte**: `string`

#### Defined in

[schemas.ts:1062](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1062)

***

### MediaSegments

Ƭ **MediaSegments**: `any`

Schema type for MediaSegments
\*
\*

#### Defined in

[schemas.ts:1068](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1068)

***

### MediaUploadAppendRequest

Ƭ **MediaUploadAppendRequest**: `any`

Schema type for MediaUploadAppendRequest
\*
\*

#### Defined in

[schemas.ts:1079](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1079)

***

### MediaWidth

Ƭ **MediaWidth**: `number`

#### Defined in

[schemas.ts:1104](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1104)

***

### MentionEntity

Ƭ **MentionEntity**: `any`

Schema type for MentionEntity
\*
\*

#### Defined in

[schemas.ts:1110](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1110)

***

### MisleadingTags

Ƭ **MisleadingTags**: `"disputed_claim_as_fact"` | `"factual_error"` | `"manipulated_media"` | `"misinterpreted_satire"` | `"missing_important_context"` | `"other"` | `"outdated_information"`

#### Defined in

[schemas.ts:1135](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1135)

***

### NewestId

Ƭ **NewestId**: `string`

#### Defined in

[schemas.ts:1150](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1150)

***

### NewsId

Ƭ **NewsId**: `string`

#### Defined in

[schemas.ts:1165](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1165)

***

### NextToken

Ƭ **NextToken**: `string`

#### Defined in

[schemas.ts:1170](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1170)

***

### NonCompliantRulesProblem

Ƭ **NonCompliantRulesProblem**: `any`

A problem that indicates the user's rule set is not compliant.
\*
\*

#### Defined in

[schemas.ts:1176](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1176)

***

### NoteClassification

Ƭ **NoteClassification**: `"misinformed_or_potentially_misleading"` | `"not_misleading"`

#### Defined in

[schemas.ts:1186](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1186)

***

### NoteId

Ƭ **NoteId**: `string`

#### Defined in

[schemas.ts:1191](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1191)

***

### NoteRatingStatus

Ƭ **NoteRatingStatus**: `"currently_rated_helpful"` | `"currently_rated_not_helpful"` | `"firm_reject"` | `"insufficient_consensus"` | `"minimum_ratings_not_met"` | `"needs_more_ratings"` | `"needs_your_help"`

#### Defined in

[schemas.ts:1201](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1201)

***

### NoteTweetText

Ƭ **NoteTweetText**: `string`

#### Defined in

[schemas.ts:1211](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1211)

***

### Oauth1PermissionsProblem

Ƭ **Oauth1PermissionsProblem**: `any`

A problem that indicates your client application does not have the required OAuth1 permissions for the requested endpoint.
\*
\*

#### Defined in

[schemas.ts:1217](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1217)

***

### OldestId

Ƭ **OldestId**: `string`

#### Defined in

[schemas.ts:1222](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1222)

***

### OperationalDisconnectProblem

Ƭ **OperationalDisconnectProblem**: `any`

You have been disconnected for operational reasons.
\*
\*

#### Defined in

[schemas.ts:1228](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1228)

***

### PaginationToken32

Ƭ **PaginationToken32**: `string`

#### Defined in

[schemas.ts:1233](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1233)

***

### PaginationToken36

Ƭ **PaginationToken36**: `string`

#### Defined in

[schemas.ts:1238](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1238)

***

### PaginationTokenLong

Ƭ **PaginationTokenLong**: `string`

#### Defined in

[schemas.ts:1243](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1243)

***

### Photo

Ƭ **Photo**: `any`

Schema type for Photo
\*
\*

#### Defined in

[schemas.ts:1254](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1254)

***

### PlaceId

Ƭ **PlaceId**: `string`

#### Defined in

[schemas.ts:1264](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1264)

***

### PlaceType

Ƭ **PlaceType**: `"poi"` | `"neighborhood"` | `"city"` | `"admin"` | `"country"` | `"unknown"`

#### Defined in

[schemas.ts:1269](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1269)

***

### PollId

Ƭ **PollId**: `string`

#### Defined in

[schemas.ts:1329](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1329)

***

### PollOptionLabel

Ƭ **PollOptionLabel**: `string`

#### Defined in

[schemas.ts:1339](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1339)

***

### Position

Ƭ **Position**: `number`\[]

#### Defined in

[schemas.ts:1344](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1344)

***

### PreviousToken

Ƭ **PreviousToken**: `string`

#### Defined in

[schemas.ts:1354](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1354)

***

### ReplySettings

Ƭ **ReplySettings**: `"everyone"` | `"mentionedUsers"` | `"following"` | `"other"`

#### Defined in

[schemas.ts:1379](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1379)

***

### ReplySettingsWithVerifiedUsers

Ƭ **ReplySettingsWithVerifiedUsers**: `"everyone"` | `"mentionedUsers"` | `"following"` | `"other"` | `"subscribers"` | `"verified"`

#### Defined in

[schemas.ts:1384](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1384)

***

### ResourceNotFoundProblem

Ƭ **ResourceNotFoundProblem**: `any`

A problem that indicates that a given Tweet, User, etc. does not exist.
\*
\*

#### Defined in

[schemas.ts:1390](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1390)

***

### ResourceUnauthorizedProblem

Ƭ **ResourceUnauthorizedProblem**: `any`

A problem that indicates you are not allowed to see a particular Tweet, User, etc.
\*
\*

#### Defined in

[schemas.ts:1396](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1396)

***

### ResourceUnavailableProblem

Ƭ **ResourceUnavailableProblem**: `any`

A problem that indicates a particular Tweet, User, etc. is not available to you.
\*
\*

#### Defined in

[schemas.ts:1402](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1402)

***

### ResultCount

Ƭ **ResultCount**: `number`

#### Defined in

[schemas.ts:1407](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1407)

***

### RuleId

Ƭ **RuleId**: `string`

#### Defined in

[schemas.ts:1417](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1417)

***

### RulesCapProblem

Ƭ **RulesCapProblem**: `any`

You have exceeded the maximum number of rules.
\*
\*

#### Defined in

[schemas.ts:1428](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1428)

***

### RulesRequestSummary

Ƭ **RulesRequestSummary**: `any`

Schema type for RulesRequestSummary
\*
\*

#### Defined in

[schemas.ts:1444](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1444)

***

### RuleTag

Ƭ **RuleTag**: `string`

#### Defined in

[schemas.ts:1454](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1454)

***

### RuleValue

Ƭ **RuleValue**: `string`

#### Defined in

[schemas.ts:1459](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1459)

***

### SpaceId

Ƭ **SpaceId**: `string`

#### Defined in

[schemas.ts:1484](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1484)

***

### Start

Ƭ **Start**: `string`

#### Defined in

[schemas.ts:1489](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1489)

***

### SubscriptionsCreateRequest

Ƭ **SubscriptionsCreateRequest**: `Record`\<`string`, `any`>

#### Defined in

[schemas.ts:1519](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1519)

***

### SubtitleLanguageCode

Ƭ **SubtitleLanguageCode**: `string`

#### Defined in

[schemas.ts:1544](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1544)

***

### TopicId

Ƭ **TopicId**: `string`

#### Defined in

[schemas.ts:1584](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1584)

***

### TweetComplianceData

Ƭ **TweetComplianceData**: `any`

Tweet compliance data.
\*
\*

#### Defined in

[schemas.ts:1600](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1600)

***

### TweetComplianceStreamResponse

Ƭ **TweetComplianceStreamResponse**: `any`

Tweet compliance stream events.
\*
\*

#### Defined in

[schemas.ts:1611](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1611)

***

### TweetCount

Ƭ **TweetCount**: `number`

#### Defined in

[schemas.ts:1616](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1616)

***

### TweetId

Ƭ **TweetId**: `string`

#### Defined in

[schemas.ts:1666](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1666)

***

### TweetLabelData

Ƭ **TweetLabelData**: `any`

Tweet label data.
\*
\*

#### Defined in

[schemas.ts:1672](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1672)

***

### TweetLabelStreamResponse

Ƭ **TweetLabelStreamResponse**: `any`

Tweet label stream events.
\*
\*

#### Defined in

[schemas.ts:1678](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1678)

***

### TweetText

Ƭ **TweetText**: `string`

#### Defined in

[schemas.ts:1698](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1698)

***

### UnsupportedAuthenticationProblem

Ƭ **UnsupportedAuthenticationProblem**: `any`

A problem that indicates that the authentication used is not supported.
\*
\*

#### Defined in

[schemas.ts:1734](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1734)

***

### UploadExpiration

Ƭ **UploadExpiration**: `string`

#### Defined in

[schemas.ts:1739](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1739)

***

### UploadUrl

Ƭ **UploadUrl**: `string`

#### Defined in

[schemas.ts:1749](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1749)

***

### Url

Ƭ **Url**: `string`

#### Defined in

[schemas.ts:1754](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1754)

***

### UrlEntity

Ƭ **UrlEntity**: `any`

Represent the portion of text recognized as a URL, and its start and end position within the text.
\*
\*

#### Defined in

[schemas.ts:1760](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1760)

***

### UrlEntityDm

Ƭ **UrlEntityDm**: `any`

Represent the portion of text recognized as a URL, and its start and end position within the text.
\*
\*

#### Defined in

[schemas.ts:1766](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1766)

***

### UsageCapExceededProblem

Ƭ **UsageCapExceededProblem**: `any`

A problem that indicates that a usage cap has been exceeded.
\*
\*

#### Defined in

[schemas.ts:1787](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1787)

***

### UserComplianceData

Ƭ **UserComplianceData**: `any`

User compliance data.
\*
\*

#### Defined in

[schemas.ts:1803](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1803)

***

### UserComplianceStreamResponse

Ƭ **UserComplianceStreamResponse**: `any`

User compliance stream events.
\*
\*

#### Defined in

[schemas.ts:1814](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1814)

***

### UserId

Ƭ **UserId**: `string`

#### Defined in

[schemas.ts:1824](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1824)

***

### UserIdMatchesAuthenticatedUser

Ƭ **UserIdMatchesAuthenticatedUser**: `string`

#### Defined in

[schemas.ts:1829](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1829)

***

### UserName

Ƭ **UserName**: `string`

#### Defined in

[schemas.ts:1834](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1834)

***

### UserSearchQueryVnext

Ƭ **UserSearchQueryVnext**: `string`

#### Defined in

[schemas.ts:1874](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1874)

***

### Variants

Ƭ **Variants**: [`Variant`](/xdks/typescript/reference/interfaces/Schemas.Variant)\[]

#### Defined in

[schemas.ts:1964](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1964)

***

### Video

Ƭ **Video**: `any`

Schema type for Video
\*
\*

#### Defined in

[schemas.ts:1970](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1970)

***

### WebhookConfigId

Ƭ **WebhookConfigId**: `string`

#### Defined in

[schemas.ts:1995](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/schemas.ts#L1995)


# Namespace: Spaces
Source: https://docs.x.com/xdks/typescript/reference/modules/Spaces

Reference for the Spaces module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### GetByIdsResponse

Ƭ **GetByIdsResponse**: [`Get2SpacesResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesResponse)

Response for getByIds

#### Defined in

[spaces/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/models.ts#L18)

***

### GetPostsResponse

Ƭ **GetPostsResponse**: [`Get2SpacesIdTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdTweetsResponse)

Response for getPosts

#### Defined in

[spaces/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/models.ts#L24)

***

### SearchResponse

Ƭ **SearchResponse**: [`Get2SpacesSearchResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesSearchResponse)

Response for search

#### Defined in

[spaces/models.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/models.ts#L30)

***

### GetBuyersResponse

Ƭ **GetBuyersResponse**: [`Get2SpacesIdBuyersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdBuyersResponse)

Response for getBuyers

#### Defined in

[spaces/models.ts:36](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/models.ts#L36)

***

### GetByIdResponse

Ƭ **GetByIdResponse**: [`Get2SpacesIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdResponse)

Response for getById

#### Defined in

[spaces/models.ts:42](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/models.ts#L42)

***

### GetByCreatorIdsResponse

Ƭ **GetByCreatorIdsResponse**: [`Get2SpacesByCreatorIdsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2SpacesByCreatorIdsResponse)

Response for getByCreatorIds

#### Defined in

[spaces/models.ts:48](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/spaces/models.ts#L48)


# Namespace: Stream
Source: https://docs.x.com/xdks/typescript/reference/modules/Stream

Reference for the Stream module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### LikesComplianceResponse

Ƭ **LikesComplianceResponse**: [`LikesComplianceStreamResponse`](/xdks/typescript/reference/modules/Schemas#likescompliancestreamresponse)

Response for likesCompliance

#### Defined in

[stream/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L18)

***

### UsersComplianceResponse

Ƭ **UsersComplianceResponse**: [`UserComplianceStreamResponse`](/xdks/typescript/reference/modules/Schemas#usercompliancestreamresponse)

Response for usersCompliance

#### Defined in

[stream/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L24)

***

### PostsFirehoseKoResponse

Ƭ **PostsFirehoseKoResponse**: [`StreamingTweetResponse`](/xdks/typescript/reference/interfaces/Schemas.StreamingTweetResponse)

Response for postsFirehoseKo

#### Defined in

[stream/models.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L30)

***

### LikesSample10Response

Ƭ **LikesSample10Response**: [`StreamingLikeResponseV2`](/xdks/typescript/reference/interfaces/Schemas.StreamingLikeResponseV2)

Response for likesSample10

#### Defined in

[stream/models.ts:36](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L36)

***

### GetRuleCountsResponse

Ƭ **GetRuleCountsResponse**: [`Get2TweetsSearchStreamRulesCountsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchStreamRulesCountsResponse)

Response for getRuleCounts

#### Defined in

[stream/models.ts:42](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L42)

***

### LikesFirehoseResponse

Ƭ **LikesFirehoseResponse**: [`StreamingLikeResponseV2`](/xdks/typescript/reference/interfaces/Schemas.StreamingLikeResponseV2)

Response for likesFirehose

#### Defined in

[stream/models.ts:48](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L48)

***

### PostsFirehoseJaResponse

Ƭ **PostsFirehoseJaResponse**: [`StreamingTweetResponse`](/xdks/typescript/reference/interfaces/Schemas.StreamingTweetResponse)

Response for postsFirehoseJa

#### Defined in

[stream/models.ts:54](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L54)

***

### PostsFirehoseEnResponse

Ƭ **PostsFirehoseEnResponse**: [`StreamingTweetResponse`](/xdks/typescript/reference/interfaces/Schemas.StreamingTweetResponse)

Response for postsFirehoseEn

#### Defined in

[stream/models.ts:60](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L60)

***

### GetRulesResponse

Ƭ **GetRulesResponse**: [`RulesLookupResponse`](/xdks/typescript/reference/interfaces/Schemas.RulesLookupResponse)

Response for getRules

#### Defined in

[stream/models.ts:66](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L66)

***

### UpdateRulesRequest

Ƭ **UpdateRulesRequest**: [`AddOrDeleteRulesRequest`](/xdks/typescript/reference/modules/Schemas#addordeleterulesrequest)

Request for updateRules

#### Defined in

[stream/models.ts:72](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L72)

***

### UpdateRulesResponse

Ƭ **UpdateRulesResponse**: [`AddOrDeleteRulesResponse`](/xdks/typescript/reference/interfaces/Schemas.AddOrDeleteRulesResponse)

Response for updateRules

#### Defined in

[stream/models.ts:78](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L78)

***

### PostsSampleResponse

Ƭ **PostsSampleResponse**: [`StreamingTweetResponse`](/xdks/typescript/reference/interfaces/Schemas.StreamingTweetResponse)

Response for postsSample

#### Defined in

[stream/models.ts:84](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L84)

***

### PostsSample10Response

Ƭ **PostsSample10Response**: [`Get2TweetsSample10StreamResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TweetsSample10StreamResponse)

Response for postsSample10

#### Defined in

[stream/models.ts:90](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L90)

***

### PostsComplianceResponse

Ƭ **PostsComplianceResponse**: [`TweetComplianceStreamResponse`](/xdks/typescript/reference/modules/Schemas#tweetcompliancestreamresponse)

Response for postsCompliance

#### Defined in

[stream/models.ts:96](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L96)

***

### LabelsComplianceResponse

Ƭ **LabelsComplianceResponse**: [`TweetLabelStreamResponse`](/xdks/typescript/reference/modules/Schemas#tweetlabelstreamresponse)

Response for labelsCompliance

#### Defined in

[stream/models.ts:102](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L102)

***

### PostsResponse

Ƭ **PostsResponse**: [`FilteredStreamingTweetResponse`](/xdks/typescript/reference/interfaces/Schemas.FilteredStreamingTweetResponse)

Response for posts

#### Defined in

[stream/models.ts:108](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L108)

***

### PostsFirehoseResponse

Ƭ **PostsFirehoseResponse**: [`StreamingTweetResponse`](/xdks/typescript/reference/interfaces/Schemas.StreamingTweetResponse)

Response for postsFirehose

#### Defined in

[stream/models.ts:114](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L114)

***

### PostsFirehosePtResponse

Ƭ **PostsFirehosePtResponse**: [`StreamingTweetResponse`](/xdks/typescript/reference/interfaces/Schemas.StreamingTweetResponse)

Response for postsFirehosePt

#### Defined in

[stream/models.ts:120](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/stream/models.ts#L120)


# Namespace: Trends
Source: https://docs.x.com/xdks/typescript/reference/modules/Trends

Reference for the Trends module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

zedResponse]\(/xdks/typescript/reference/modules/Trends#getpersonalizedresponse)

## Type Aliases

### GetByWoeidResponse

Ƭ **GetByWoeidResponse**: [`Get2TrendsByWoeidWoeidResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2TrendsByWoeidWoeidResponse)

Response for getByWoeid

#### Defined in

[trends/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/trends/models.ts#L18)

***

### GetPersonalizedResponse

Ƭ **GetPersonalizedResponse**: [`Get2UsersPersonalizedTrendsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersPersonalizedTrendsResponse)

Response for getPersonalized

#### Defined in

[trends/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/trends/models.ts#L24)


# Namespace: Usage
Source: https://docs.x.com/xdks/typescript/reference/modules/Usage

Reference for the Usage module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### GetResponse

Ƭ **GetResponse**: [`Get2UsageTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsageTweetsResponse)

Response for get

#### Defined in

[usage/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/usage/models.ts#L18)


# Namespace: Users
Source: https://docs.x.com/xdks/typescript/reference/modules/Users

Reference for the Users module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## References

### MuteUserRequest

Re-exports [MuteUserRequest](/xdks/typescript/reference/interfaces/Schemas.MuteUserRequest)

## Type Aliases

### GetByUsernamesResponse

Ƭ **GetByUsernamesResponse**: [`Get2UsersByResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersByResponse)

Response for getByUsernames

#### Defined in

[users/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L18)

***

### GetRepostsOfMeResponse

Ƭ **GetRepostsOfMeResponse**: [`Get2UsersRepostsOfMeResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersRepostsOfMeResponse)

Response for getRepostsOfMe

#### Defined in

[users/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L24)

***

### UnlikePostResponse

Ƭ **UnlikePostResponse**: [`UsersLikesDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersLikesDeleteResponse)

Response for unlikePost

#### Defined in

[users/models.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L30)

***

### GetBookmarksResponse

Ƭ **GetBookmarksResponse**: [`Get2UsersIdBookmarksResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBookmarksResponse)

Response for getBookmarks

#### Defined in

[users/models.ts:36](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L36)

***

### CreateBookmarkRequest

Ƭ **CreateBookmarkRequest**: [`BookmarkAddRequest`](/xdks/typescript/reference/interfaces/Schemas.BookmarkAddRequest)

Request for createBookmark

#### Defined in

[users/models.ts:42](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L42)

***

### CreateBookmarkResponse

Ƭ **CreateBookmarkResponse**: [`BookmarkMutationResponse`](/xdks/typescript/reference/interfaces/Schemas.BookmarkMutationResponse)

Response for createBookmark

#### Defined in

[users/models.ts:48](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L48)

***

### GetFollowersResponse

Ƭ **GetFollowersResponse**: [`Get2UsersIdFollowersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowersResponse)

Response for getFollowers

#### Defined in

[users/models.ts:54](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L54)

***

### UnpinListResponse

Ƭ **UnpinListResponse**: [`ListUnpinResponse`](/xdks/typescript/reference/interfaces/Schemas.ListUnpinResponse)

Response for unpinList

#### Defined in

[users/models.ts:60](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L60)

***

### GetByIdResponse

Ƭ **GetByIdResponse**: [`Get2UsersIdResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdResponse)

Response for getById

#### Defined in

[users/models.ts:66](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L66)

***

### GetMentionsResponse

Ƭ **GetMentionsResponse**: [`Get2UsersIdMentionsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMentionsResponse)

Response for getMentions

#### Defined in

[users/models.ts:72](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L72)

***

### UnrepostPostResponse

Ƭ **UnrepostPostResponse**: [`UsersRetweetsDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsDeleteResponse)

Response for unrepostPost

#### Defined in

[users/models.ts:78](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L78)

***

### DeleteBookmarkResponse

Ƭ **DeleteBookmarkResponse**: [`BookmarkMutationResponse`](/xdks/typescript/reference/interfaces/Schemas.BookmarkMutationResponse)

Response for deleteBookmark

#### Defined in

[users/models.ts:84](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L84)

***

### UnfollowListResponse

Ƭ **UnfollowListResponse**: [`ListFollowedResponse`](/xdks/typescript/reference/interfaces/Schemas.ListFollowedResponse)

Response for unfollowList

#### Defined in

[users/models.ts:90](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L90)

***

### UnmuteUserResponse

Ƭ **UnmuteUserResponse**: [`MuteUserMutationResponse`](/xdks/typescript/reference/interfaces/Schemas.MuteUserMutationResponse)

Response for unmuteUser

#### Defined in

[users/models.ts:96](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L96)

***

### GetMeResponse

Ƭ **GetMeResponse**: [`Get2UsersMeResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersMeResponse)

Response for getMe

#### Defined in

[users/models.ts:102](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L102)

***

### GetMutingResponse

Ƭ **GetMutingResponse**: [`Get2UsersIdMutingResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMutingResponse)

Response for getMuting

#### Defined in

[users/models.ts:108](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L108)

***

### MuteUserResponse

Ƭ **MuteUserResponse**: [`MuteUserMutationResponse`](/xdks/typescript/reference/interfaces/Schemas.MuteUserMutationResponse)

Response for muteUser

#### Defined in

[users/models.ts:121](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L121)

***

### SearchResponse

Ƭ **SearchResponse**: [`Get2UsersSearchResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersSearchResponse)

Response for search

#### Defined in

[users/models.ts:127](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L127)

***

### GetBlockingResponse

Ƭ **GetBlockingResponse**: [`Get2UsersIdBlockingResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBlockingResponse)

Response for getBlocking

#### Defined in

[users/models.ts:133](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L133)

***

### GetByIdsResponse

Ƭ **GetByIdsResponse**: [`Get2UsersResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersResponse)

Response for getByIds

#### Defined in

[users/models.ts:139](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L139)

***

### GetFollowingResponse

Ƭ **GetFollowingResponse**: [`Get2UsersIdFollowingResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowingResponse)

Response for getFollowing

#### Defined in

[users/models.ts:145](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L145)

***

### FollowUserRequest

Ƭ **FollowUserRequest**: [`UsersFollowingCreateRequest`](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateRequest)

Request for followUser

#### Defined in

[users/models.ts:151](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L151)

***

### FollowUserResponse

Ƭ **FollowUserResponse**: [`UsersFollowingCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateResponse)

Response for followUser

#### Defined in

[users/models.ts:157](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L157)

***

### LikePostRequest

Ƭ **LikePostRequest**: [`UsersLikesCreateRequest`](/xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateRequest)

Request for likePost

#### Defined in

[users/models.ts:163](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L163)

***

### LikePostResponse

Ƭ **LikePostResponse**: [`UsersLikesCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateResponse)

Response for likePost

#### Defined in

[users/models.ts:169](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L169)

***

### GetLikedPostsResponse

Ƭ **GetLikedPostsResponse**: [`Get2UsersIdLikedTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdLikedTweetsResponse)

Response for getLikedPosts

#### Defined in

[users/models.ts:175](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L175)

***

### GetPostsResponse

Ƭ **GetPostsResponse**: [`Get2UsersIdTweetsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTweetsResponse)

Response for getPosts

#### Defined in

[users/models.ts:181](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L181)

***

### BlockDmsResponse

Ƭ **BlockDmsResponse**: [`UsersDMBlockCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersDMBlockCreateResponse)

Response for blockDms

#### Defined in

[users/models.ts:187](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L187)

***

### GetListMembershipsResponse

Ƭ **GetListMembershipsResponse**: [`Get2UsersIdListMembershipsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdListMembershipsResponse)

Response for getListMemberships

#### Defined in

[users/models.ts:193](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L193)

***

### GetPinnedListsResponse

Ƭ **GetPinnedListsResponse**: [`Get2UsersIdPinnedListsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdPinnedListsResponse)

Response for getPinnedLists

#### Defined in

[users/models.ts:199](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L199)

***

### PinListRequest

Ƭ **PinListRequest**: [`ListPinnedRequest`](/xdks/typescript/reference/interfaces/Schemas.ListPinnedRequest)

Request for pinList

#### Defined in

[users/models.ts:205](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L205)

***

### PinListResponse

Ƭ **PinListResponse**: [`ListPinnedResponse`](/xdks/typescript/reference/interfaces/Schemas.ListPinnedResponse)

Response for pinList

#### Defined in

[users/models.ts:211](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L211)

***

### GetByUsernameResponse

Ƭ **GetByUsernameResponse**: [`Get2UsersByUsernameUsernameResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersByUsernameUsernameResponse)

Response for getByUsername

#### Defined in

[users/models.ts:217](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L217)

***

### UnfollowUserResponse

Ƭ **UnfollowUserResponse**: [`UsersFollowingDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersFollowingDeleteResponse)

Response for unfollowUser

#### Defined in

[users/models.ts:223](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L223)

***

### GetTimelineResponse

Ƭ **GetTimelineResponse**: [`Get2UsersIdTimelinesReverseChronologicalResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTimelinesReverseChronologicalResponse)

Response for getTimeline

#### Defined in

[users/models.ts:229](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L229)

***

### GetFollowedListsResponse

Ƭ **GetFollowedListsResponse**: [`Get2UsersIdFollowedListsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowedListsResponse)

Response for getFollowedLists

#### Defined in

[users/models.ts:235](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L235)

***

### FollowListRequest

Ƭ **FollowListRequest**: [`ListFollowedRequest`](/xdks/typescript/reference/interfaces/Schemas.ListFollowedRequest)

Request for followList

#### Defined in

[users/models.ts:241](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L241)

***

### FollowListResponse

Ƭ **FollowListResponse**: [`ListFollowedResponse`](/xdks/typescript/reference/interfaces/Schemas.ListFollowedResponse)

Response for followList

#### Defined in

[users/models.ts:247](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L247)

***

### UnblockDmsResponse

Ƭ **UnblockDmsResponse**: [`UsersDMUnBlockCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersDMUnBlockCreateResponse)

Response for unblockDms

#### Defined in

[users/models.ts:253](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L253)

***

### RepostPostRequest

Ƭ **RepostPostRequest**: [`UsersRetweetsCreateRequest`](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateRequest)

Request for repostPost

#### Defined in

[users/models.ts:259](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L259)

***

### RepostPostResponse

Ƭ **RepostPostResponse**: [`UsersRetweetsCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateResponse)

Response for repostPost

#### Defined in

[users/models.ts:265](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L265)

***

### GetBookmarkFoldersResponse

Ƭ **GetBookmarkFoldersResponse**: [`BookmarkFoldersResponse`](/xdks/typescript/reference/interfaces/Schemas.BookmarkFoldersResponse)

Response for getBookmarkFolders

#### Defined in

[users/models.ts:271](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L271)

***

### GetOwnedListsResponse

Ƭ **GetOwnedListsResponse**: [`Get2UsersIdOwnedListsResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2UsersIdOwnedListsResponse)

Response for getOwnedLists

#### Defined in

[users/models.ts:277](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L277)

***

### GetBookmarksByFolderIdResponse

Ƭ **GetBookmarksByFolderIdResponse**: [`BookmarkFolderPostsResponse`](/xdks/typescript/reference/interfaces/Schemas.BookmarkFolderPostsResponse)

Response for getBookmarksByFolderId

#### Defined in

[users/models.ts:283](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/users/models.ts#L283)


# Namespace: Webhooks
Source: https://docs.x.com/xdks/typescript/reference/modules/Webhooks

Reference for the Webhooks module in the X API TypeScript SDK. Re-exported clients, types, and utilities provided by this SDK module for the X API v2.

## Type Aliases

### CreateStreamLinkResponse

Ƭ **CreateStreamLinkResponse**: [`WebhookLinksCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksCreateResponse)

Response for createStreamLink

#### Defined in

[webhooks/models.ts:18](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/models.ts#L18)

***

### DeleteStreamLinkResponse

Ƭ **DeleteStreamLinkResponse**: [`WebhookLinksDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksDeleteResponse)

Response for deleteStreamLink

#### Defined in

[webhooks/models.ts:24](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/models.ts#L24)

***

### GetStreamLinksResponse

Ƭ **GetStreamLinksResponse**: [`WebhookLinksGetResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookLinksGetResponse)

Response for getStreamLinks

#### Defined in

[webhooks/models.ts:30](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/models.ts#L30)

***

### CreateWebhookReplayJobRequest

Ƭ **CreateWebhookReplayJobRequest**: [`WebhookReplayCreateRequest`](/xdks/typescript/reference/interfaces/Schemas.WebhookReplayCreateRequest)

Request for createWebhookReplayJob

#### Defined in

[webhooks/models.ts:36](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/models.ts#L36)

***

### CreateWebhookReplayJobResponse

Ƭ **CreateWebhookReplayJobResponse**: [`ReplayJobCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.ReplayJobCreateResponse)

Response for createWebhookReplayJob

#### Defined in

[webhooks/models.ts:42](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/models.ts#L42)

***

### ValidateResponse

Ƭ **ValidateResponse**: [`WebhookConfigPutResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigPutResponse)

Response for validate

#### Defined in

[webhooks/models.ts:48](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/models.ts#L48)

***

### DeleteResponse

Ƭ **DeleteResponse**: [`WebhookConfigDeleteResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigDeleteResponse)

Response for delete

#### Defined in

[webhooks/models.ts:54](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/models.ts#L54)

***

### GetResponse

Ƭ **GetResponse**: [`Get2WebhooksResponse`](/xdks/typescript/reference/interfaces/Schemas.Get2WebhooksResponse)

Response for get

#### Defined in

[webhooks/models.ts:60](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/models.ts#L60)

***

### CreateRequest

Ƭ **CreateRequest**: [`WebhookConfigCreateRequest`](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateRequest)

Request for create

#### Defined in

[webhooks/models.ts:66](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/models.ts#L66)

***

### CreateResponse

Ƭ **CreateResponse**: [`WebhookConfigCreateResponse`](/xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateResponse)

Response for create

#### Defined in

[webhooks/models.ts:72](https://github.com/xdevplatform/xdk-typescript/blob/81aacb165e0802e188f608bdf462b60fc4e713a2/src/webhooks/models.ts#L72)


# Streaming
Source: https://docs.x.com/xdks/typescript/streaming

Stream real-time X API data in TypeScript using event listeners or async iteration for sampled posts, with automatic reconnection and stream lifecycle control.

The TypeScript SDK provides real-time streaming capabilities for live data feeds.

## Basic Streaming

Connect to real-time sampled posts:

<CodeGroup>
  ```typescript title="stream.ts" lines wrap icon="square-js" theme={null} theme={null}
  import { Client } from '@xdevplatform/xdk';

  const client: Client = new Client({ bearerToken: 'your-bearer-token' });

  // 1% sampled public posts
  const stream = await client.stream.postsSample({
    tweetFields: ['id','text','created_at'],
    expansions: ['author_id'],
    userFields: ['id','username','name']
  });

  // Listen to events
  stream.on('data', (event) => {
    // event is the parsed JSON line (data/includes/matching_rules)
    console.log('New data:', event);
  });

  stream.on('error', (e) => console.error('Stream error:', e));
  stream.on('close', () => console.log('Stream closed'));
  ```

  ```javascript stream.js theme={null} theme={null}
  import { Client } from '@xdevplatform/xdk';

  const client = new Client({ bearerToken: 'your-bearer-token' });
  const stream = await client.stream.postsSample({ tweetFields: ['id','text'] });

  stream.on('data', (event) => {
    console.log('New data:', event);
  });
  stream.on('error', (e) => console.error('Stream error:', e));
  stream.on('close', () => console.log('Stream closed'));
  ```
</CodeGroup>

## Async Iteration

Consume the stream with async iteration:

<CodeGroup>
  ```typescript async.ts theme={null} theme={null}
  const stream = await client.stream.postsSample();
  for await (const event of stream) {
    // Each event is a parsed JSON line (data/includes/matching_rules)
    console.log(event);
  }
  ```

  ```javascript async.js theme={null} theme={null}
  const stream = await client.stream.postsSample();
  for await (const event of stream) {
    console.log(event);
  }
  ```
</CodeGroup>

## Stream Management

Control lifecycle from the event-driven stream:

```typescript theme={null}
// Close the stream
stream.close();

// Auto-reconnect (if enabled by your wrapper)
// The default EventDrivenStream exposes basic reconnect hooks
```

## Error Handling

Handle streaming errors and reconnections:

```typescript theme={null}
stream.on('error', (event) => {
  const err = event.error || event;
  console.error('Stream error:', err);
});

stream.on('keepAlive', () => {
  // heartbeat event
});
```

<Info>
  For detailed code examples using the Javascript/TypeScript XDK, check out our [code samples GitHub repo](https://github.com/xdevplatform/samples/tree/main/javascript).
</Info>