X API

https://docs.x.com
Admin
The X API offers developers immediate access to X data and powerful tools to build applications,...
Tokens:3,347,366
Snippets:19,451
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example output from xurl webhook start

Source: https://docs.x.com/x-api/webhooks/quickstart

Example output showing the server startup process, including ngrok tunnel setup and the webhook URL to use for registration.

```text
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...

```

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

### Install via Go install and start the playground

Source: https://docs.x.com/tools/playground

Install the playground using `go install` and start the server. Requires Go 1.21+. The server starts at `http://localhost:8080` by default.

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

```

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

### Quick start: get user by username

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

Quick start example: create a client with a bearer token and fetch a user by username. Demonstrates the basic usage of the XDK client.

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

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

### Python SDK quick start: install and search recent posts

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

Install the Python SDK and run a quick search for recent posts. The example creates a client with a bearer token and prints the first post's text from the search results.

```bash
pip install xdk
```

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

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

### Install and start API Playground with Go install

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

Installs the API Playground mock server from source using Go 1.21+ and starts it. The server runs at http://localhost:8080 by default.

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

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

### Get Product Set - Example Request

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

Example GET request to retrieve details for a specific product set.

```http
GET https://ads-api.x.com/12/product_catalogs/1547080201384865792/product_sets/1560456755976343552
```

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

### Expected Output from Quickstart

Source: https://docs.x.com/xdks/python/quickstart

Example output showing the expected result when the script runs successfully.

```text
Latest Post: Exciting updates on XDK Python SDK!

```

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

### Python requests example for liking users

Source: https://docs.x.com/x-api/posts/get-liking-users

Uses the requests library to make a GET request. Requires the requests package to be installed.

```python
import requests

url = "https://api.x.com/2/tweets/{id}/liking_users?max_results=100"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

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

### Run Quickstart Script

Source: https://docs.x.com/xdks/python/quickstart

Command to run the quickstart.py script after creating it.

```bash
python quickstart.py

```

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

### GET /2/users/{id}/following - Client Examples

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

These are the client examples for the GET /2/users/{id}/following endpoint. Each example sends a GET request to the URL with an Authorization header containing a bearer token. The response is printed or logged. The cURL example uses the --request GET flag and the --url option. The Python example uses the requests library. The JavaScript example uses fetch. The PHP example uses cURL with CURLOPT_CUSTOMREQUEST set to "GET". The Go example uses net/http. The Java example uses Unirest. The Ruby example uses net/http.

```bash
curl --request GET \
  --url https://api.x.com/2/users/{id}/following \
  --header 'Authorization: Bearer <token>'
```

```python
import requests

url = "https://api.x.com/2/users/{id}/following"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.x.com/2/users/{id}/following', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.x.com/2/users/{id}/following",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.com/2/users/{id}/following"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://api.x.com/2/users/{id}/following")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.x.com/2/users/{id}/following")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

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

### Build from source and start the playground

Source: https://docs.x.com/tools/playground

Clone the repository, build the binary, and start the playground. The server starts at `http://localhost:8080` by default.

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

```

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

### TypeScript SDK quick start: get user by username

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

Initialize the TypeScript client with a bearer token and fetch a user by username. The example logs the username from the response data.

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

```

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

### GET scheduled_feeds - Example Response

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

Example response for the GET scheduled_feeds request, showing the list of scheduled feeds.

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

```

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

### Go example for user bookmarks

Source: https://docs.x.com/x-api/bookmarks/bookmarks-by-user

Go example using net/http to fetch user bookmarks. Replace {id} and <token> as needed.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.com/2/users/{id}/bookmarks"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Get blocked users (v2) - cURL, Python, JavaScript

Source: https://docs.x.com/x-api/users/blocks/migrate

Retrieves a list of users blocked by a specified user (v2). Requires OAuth 1.0a User Context authentication. The cURL example uses an OAuth placeholder; the Python and JavaScript examples show full authentication setup and pagination handling.

```shellscript
curl "https://api.x.com/2/users/123456789/blocking?user.fields=username,verified&max_results=100" \
  -H "Authorization: OAuth ..."
```

```python
# Requires OAuth 1.0a User Context authentication
import requests
from requests_oauthlib import OAuth1

auth = OAuth1(
    "API_KEY", "API_SECRET",
    "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET"
)

url = "https://api.x.com/2/users/123456789/blocking"
params = {"user.fields": "username,verified", "max_results": 100}

response = requests.get(url, auth=auth, params=params)
print(response.json())
```

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

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

### Go example for user bookmarks

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

Uses net/http to send a GET request to the X API. Reads the response body and prints it.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.com/2/users/{id}/bookmarks"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### Get media creative by ID - Example Request

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

Example GET request to retrieve a specific media creative by its ID.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3
```

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

### Python SDK quick start

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

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

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

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

### Go example for GET /2/users/by

Source: https://docs.x.com/x-api/users/get-users-by-usernames

Go example using net/http to call the endpoint. Replace <token> with your Bearer token.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.com/2/users/by"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Ruby example to get a broadcast

Source: https://docs.x.com/livestream-api/broadcasts/get-broadcast-by-id

Ruby example using net/http to GET a broadcast. Replace {id} and <token> as needed.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.x.com/2/broadcasts/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

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

### Go example to get a broadcast

Source: https://docs.x.com/livestream-api/broadcasts/get-broadcast-by-id

Go example using net/http to GET a broadcast. Replace {id} and <token> as needed.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.com/2/broadcasts/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Go example for initialize media upload

Source: https://docs.x.com/x-api/media/initialize-media-upload

Uses net/http to send a POST request with a JSON payload. Reads and prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.com/2/media/upload/initialize"

	payload := strings.NewReader("{\n  \"additional_owners\": [\n    \"<string>\"\n  ],\n  \"shared\": true,\n  \"total_bytes\": 8589934592\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Set up Go HTTP client

Source: https://docs.x.com/xchat/getting-started

Set up the HTTP client for the Go XDK using a user access token from the `X_ACCESS_TOKEN` environment variable.

```go
accessToken := os.Getenv("X_ACCESS_TOKEN")
httpClient := &http.Client{Timeout: 30 * time.Second}
```

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

### Make full-archive Post counts request with JavaScript xdk

Source: https://docs.x.com/x-api/posts/counts/quickstart/full-archive-tweet-counts

JavaScript example using the xdk Client to get full-archive Post counts. Logs each bucket's start time and tweet count, plus the total.

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

```

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

### Go example for creating bookmark

Source: https://docs.x.com/x-api/bookmarks/add-post-to-bookmarks

Uses net/http to send a POST request with a JSON payload. Prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.com/2/users/{id}/bookmarks"

	payload := strings.NewReader("{\n  \"tweet_id\": \"<string>\",\n  \"folder_id\": \"<string>\",\n  \"tweet_ids\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Make full-archive Post counts request with Python xdk

Source: https://docs.x.com/x-api/posts/counts/quickstart/full-archive-tweet-counts

Python example using the xdk Client to get full-archive Post counts. Prints each bucket's start time and tweet count, plus the total.

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

```

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

### Go example for chat settings

Source: https://docs.x.com/x-api/chat/get-chat-settings

Go example using net/http to fetch chat settings. Replace <token> with your access token.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.com/2/chat/settings"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Go example using net/http

Source: https://docs.x.com/x-api/chat/get-pending-admin-requests-for-a-chat-group-conversation

Go example using the standard net/http package to fetch pending admin requests. Replace {id} and <token> as needed.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.com/2/chat/conversations/{id}/admin_requests"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### GET active entities request

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

Example request to retrieve active entities for a specified account and entity type. The request uses the account ID '18ce54d4x5t' and filters by entity type PROMOTED_TWEET with a start and end time.

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

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

### Go example for initializing chat media upload

Source: https://docs.x.com/x-api/chat/initialize-chat-media-upload

Uses net/http to send a POST request with a JSON payload. Prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.com/2/chat/media/upload/initialize"

	payload := strings.NewReader("{\n  \"conversation_id\": \"<string>\",\n  \"total_bytes\": 1\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### GET product_catalogs - Example Response

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

Example JSON response for the GET product_catalogs request, showing a catalog object with id and name.

```json
{
  "request": {
    "params": {}
  },
  "next_cursor": null,
  "data": [
    {
      "id": "1547080201384865792",
      "name": "Catalog Name"
    }
  ]
}

```

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

### Install Python SDK with pip

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

Install the official Python SDK using pip. This is the first step in the Python quick start.

```bash
pip install xdk

```
Tokens:
Raw