### Install and Start API Playground

Source: https://docs.x.com/llms-full.txt

Install the playground server using Go or build it from source to start the local mock server.

```bash
go install github.com/xdevplatform/playground/cmd/playground@latest
playground start
```

```bash
git clone https://github.com/xdevplatform/playground.git
cd playground
go build -o playground ./cmd/playground
./playground start
```

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

### Example GET Request

Source: https://docs.x.com/llms-full.txt

A sample GET request to retrieve card information.

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

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

### Install requests library

Source: https://docs.x.com/llms-full.txt

Required dependency for executing the provided Python examples.

```bash
pip install requests
```

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

### Retrieve Products via GET

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

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

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

```json
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792",
      "count": 1
    }
  },
  "next_cursor": "1547080787865939970",
  "data": [
    {
      "inventory": 5,
      "custom_label_2": null,
      "item_group_key": null,
      "additional_image_link": null,
      "size": null,
      "mobile_link": null,
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
      "price": "20.00 USD",
      "gtin": null,
      "age_group": "teen",
      "availability": "in stock",
      "product_type": "",
      "color": null,
      "custom_label_3": null,
      "item_group_id": null,
      "brand": "X",
      "product_key": "1547080787865939969",
      "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"
    }
  ]
}
```

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

### Example GET Response

Source: https://docs.x.com/llms-full.txt

A sample response body for a card retrieval request.

```json
{
  "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"
    }
  ]
}
```

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

### Quick start with Python XDK

Source: https://docs.x.com/llms-full.txt

Initialize the client with a bearer token and perform a recent search for posts.

```python
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
```

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

### Run Python Script

Source: https://docs.x.com/llms-full.txt

Execute the quickstart script from the command line.

```bash
python quickstart.py
```

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

### EntityIndicesInclusiveInclusive Schema Example

Source: https://docs.x.com/x-api/lists/get-list-posts

Example values for inclusive start and end indices.

```yaml
example: 61
        start:
          type: integer
          description: >-
            Index (zero-based) at which position this entity starts.  The index
            is inclusive.
          minimum: 0
          example: 50
```

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

### Initialize and use Python Client

Source: https://docs.x.com/enterprise-api/tools-and-libraries

Example of initializing the Python client and performing a recent post search.

```python
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
```

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

### Entity Indices Inclusive Example

Source: https://docs.x.com/enterprise-api/stream/stream-korean-posts

Example values for inclusive start and end indices.

```yaml
end:
  example: 61
start:
  example: 50
```

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

### Entity Indices Inclusive-Inclusive Example

Source: https://docs.x.com/enterprise-api/bookmarks/get-bookmarks

Example values for start and end indices where both are inclusive.

```yaml
example:
        end: 61
        start: 50
```

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

### Clone and Setup Development Environment

Source: https://docs.x.com/llms-full.txt

Commands to clone the repository and navigate to the Python directory for local development.

```bash
git clone https://github.com/xdevplatform/xdk.git
cd xdk/python
```

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

### Quick start with XDK

Source: https://docs.x.com/llms-full.txt

Initialize the client with a bearer token and perform a basic user lookup.

```typescript
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);
```

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

### Entity Indices Example

Source: https://docs.x.com/enterprise-api/direct-messages/get-dm-event-by-id

Example values for inclusive start and exclusive end indices of an entity.

```yaml
end: 61
start: 50
```

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

### Example Metadata Values

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

Sample values for app_id, date, and filename.

```text
app_id:858382169
```

```text
date:2022-03-13
```

```text
creative_file: eiffel_tower.jpg
```

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

### Entity Indices Inclusive-Inclusive Example

Source: https://docs.x.com/enterprise-api/users/get-followers

Example values for a boundary range where both start and end indices are inclusive.

```json
{
  "end": 61,
  "start": 50
}
```

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

### Install Python SDK

Source: https://docs.x.com/enterprise-api/tools-and-libraries

Use pip to install the official X Python SDK.

```bash
pip install xdk
```

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

### Entity Indices Inclusive Range Example

Source: https://docs.x.com/enterprise-api/direct-messages/get-dm-events-for-a-dm-conversation

Example values for start and end indices of a recognized entity.

```yaml
end:
  type: integer
  description: >-
    Index (zero-based) at which position this entity ends.  The index
    is inclusive.
  minimum: 0
  example: 61
start:
  type: integer
  description: >-
    Index (zero-based) at which position this entity starts.  The index
    is inclusive.
  minimum: 0
  example: 50
```

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

### Retrieve reach analytics via GET request

Source: https://docs.x.com/llms-full.txt

Example of a GET request to the reach analytics endpoint with required query parameters.

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

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

### Client.__init__

Source: https://docs.x.com/llms-full.txt

Initializes the X API client with authentication credentials and configuration.

```APIDOC
## __init__(base_url, bearer_token, access_token, client_id, client_secret, redirect_uri, token, scopes, auth_base_url, oauth1)

### Description
Initializes the X API client. Handles configuration for app-only authentication, OAuth2 PKCE flows, and OAuth1.0a.

### Parameters
- **base_url** (str) - The base URL for the X API (defaults to https://api.x.com).
- **bearer_token** (str or None) - The bearer token for the X API (app-only authentication).
- **access_token** (str or None) - The OAuth2 access token for user context.
- **client_id** (str or None) - The client ID for the X API (required for OAuth2 PKCE flow).
- **client_secret** (str or None) - The client secret for the X API.
- **redirect_uri** (str or None) - The redirect URI for OAuth2 authorization.
- **token** (Dict[str, Any] or None) - An existing OAuth2 token dictionary.
- **scopes** (str or List[str] or None) - Space-separated string or list of strings for OAuth2 authorization scopes.
- **auth_base_url** (str) - The base URL for OAuth2 authorization (defaults to https://x.com/i).
- **oauth1** (OAuth1) - OAuth1 instance for OAuth1.0a authentication.
```

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

### Retrieve Funding Instruments via GET Request

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

Example response for a GET request to the funding_instruments endpoint, showing a CREDIT_LINE type instrument.

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

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

### Install X SDK

Source: https://docs.x.com/llms-full.txt

Installation commands for the official Python and TypeScript SDKs.

```bash
pip install xdk
```

```bash
npm install @xdevplatform/xdk
```

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

### Create a Post

Source: https://docs.x.com/enterprise-api/posts/manage-tweets/integrate

Use these examples to publish a new post to X.

```bash
curl -X POST "https://api.x.com/2/tweets" \
  -H "Authorization: OAuth ..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world!"}'
```

```python
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
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}`);
```

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

### GET targeting_criteria/interests Request

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

Example request for retrieving interest-based targeting criteria.

```http
GET https://ads-api.x.com/12/targeting_criteria/interests?q=books
```

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

### Initialize XDK Client

Source: https://docs.x.com/llms-full.txt

Import the Client class to begin any authentication flow.

```python
from xdk import Client
```

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

### GET targeting_criteria/events Request

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

Example request for retrieving event-based targeting criteria.

```http
GET https://ads-api.x.com/12/targeting_criteria/events?count=1
```

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

### Install X API Playground

Source: https://docs.x.com/llms-full.txt

Use this command to install the local server emulator for X API v2 development.

```bash
go install github.com/xdevplatform/playground/cmd/playground@latest
```

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

### Example query syntax

Source: https://docs.x.com/enterprise-api/posts/counts/introduction

Demonstrates the query syntax used for post counts, which is identical to search endpoints.

```text
python lang:en -is:retweet
```

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

### Retrieve Tweet Previews

Source: https://docs.x.com/llms-full.txt

Example GET request to retrieve previews for published tweets.

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

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

### Create Manual Product Set Request

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

Example of creating a product set using the MANUAL type with specific product keys.

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

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

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

### GET targeting_criteria/interests Response

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

Example JSON response for the interests targeting criteria endpoint.

```json
{
      "data": [
        {
          "name": "Books and literature/Biographies and memoirs",
          "targeting_type": "INTEREST",
          "targeting_value": "1001"
        }
      ],
      "request": {
        "params": {
          "q": "books",
          "count": 1
        }
      },
      "next_cursor": "6by4n4"
    }
```

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

### GET targeting_criteria/events Response

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

Example JSON response for the events targeting criteria endpoint.

```json
{
      "request": {
        "params": {
          "count": 1
        }
      },
      "data_type": "events",
      "data": [
        {
          "reach": {
            "total_reach": null
          },
          "name": "New Year's",
          "start_time": "2017-12-31T00:00:00Z",
          "top_users": [],
          "top_tweets": [],
          "top_hashtags": [],
          "gender_breakdown_percentage": {},
          "end_time": "2018-01-02T00:00:00Z",
          "country_code": null,
          "device_breakdown_percentage": {},
          "targeting_value": "1ex",
          "is_global": true,
          "event_type": "HOLIDAY",
          "country_breakdown_percentage": {}
        }
      ],
      "next_cursor": "uww0"
    }
```

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

### Render a navigation button

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

Usage of the Button component to link to the getting started documentation.

```jsx
<Button href="/x-ads-api/getting-started">
  Get started
</Button>
```

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

### Practical search query examples

Source: https://docs.x.com/x-api/fundamentals/post-annotations

Examples of using context annotations within search query parameters.

```bash
# Posts about the NBA
query=context:26.852137520

# Posts about Apple products
query=context:47.10026792024

# Posts about movies
query=context:86.*
```

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

### Retrieve Single Card Request

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

Example GET request to retrieve a specific card by ID.

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

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

### List Lookup Request Examples

Source: https://docs.x.com/enterprise-api/lists/list-lookup/integrate

Examples demonstrating how to retrieve List details by ID using different SDKs and cURL.

```bash
curl "https://api.x.com/2/lists/84839422?\
  list.fields=description,member_count,follower_count,private" \
    -H "Authorization: Bearer $BEARER_TOKEN"
```

```python
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
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);
```

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

### Initialize and use TypeScript Client

Source: https://docs.x.com/enterprise-api/tools-and-libraries

Example of initializing the TypeScript client and fetching user data by username.

```typescript
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);
```

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

### Conversion Event API Request

Source: https://docs.x.com/llms-full.txt

Example of a GET request to the conversion_event endpoint with various query parameters.

```http
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
```

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

### Retrieve Tracking Tags Request

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

Example of a GET request to fetch tracking tags for a specific account.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?tracking_tag_ids=3m82
```

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

### Install xurl via Go

Source: https://docs.x.com/llms-full.txt

Install the xurl CLI tool using the Go package manager.

```bash
go install github.com/xdevplatform/xurl@latest
```

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

### Initialize and use the X API Client

Source: https://docs.x.com/llms-full.txt

Demonstrates how to instantiate the Client with a bearer token and perform common operations like fetching user data and paginating through followers.

```typescript
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);
}
```

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

### Retrieve Draft Tweets Request

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

Example GET request to fetch draft tweets for a specific account.

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