# Twitter/X (/docs/twitter)



Twitter/X [#twitterx]

X (formerly Twitter) profiles and their tweets, individual tweets in full, community pages and their posts, video transcripts, an AI-answered search over the network, and a composite that returns a profile with computed analytics in one call.

X remains the primary platform for real-time public conversation and news, and it is also the platform with the tightest read limits — most of the design decisions below follow from that.

Base URL: `/v1/twitter/...`

How do I get started with Twitter/X data? [#how-do-i-get-started-with-twitterx-data]

1\. Fetch a profile [#1-fetch-a-profile]

```bash
curl "https://www.socialcrawl.dev/v1/twitter/profile?handle=elonmusk" \
  -H "x-api-key: sc_your_api_key_here"
```

2\. Fetch their content [#2-fetch-their-content]

```bash
curl "https://www.socialcrawl.dev/v1/twitter/user/tweets?handle=elonmusk" \
  -H "x-api-key: sc_your_api_key_here"
```

3\. Read computed fields [#3-read-computed-fields]

When an endpoint supports a computed field and the required source inputs are present, the unified response includes that optional field. Depending on the endpoint, optional fields can include `engagement_rate`, `language`, `content_category`, and `estimated_reach`. See [Computed fields](/docs/computed-fields.md) for formulas, clamping rules, and null semantics.

What you can get [#what-you-can-get]

**Accounts.** `GET /v1/twitter/profile` (1cr) takes a `handle` and returns follower, following and tweet counts, bio, profile and banner images, and verification status. `GET /v1/twitter/user/tweets` (1cr) returns up to the 100 most recent tweets for that handle with full text, like/retweet/reply counts, media, and timestamps.

**One tweet.** `GET /v1/twitter/tweet` (1cr) takes the tweet `url` and returns the complete record — including the **quote count**, which the user timeline does not carry. If quote volume matters to you, that is the reason to spend the extra call.

**Video speech.** `GET /v1/twitter/tweet/transcript` (10cr) returns the spoken words from a video attached to a tweet, auto-generated captions included. `tweet` returns the media attachment; this returns what is said in it.

**Communities.** `GET /v1/twitter/community` (1cr) takes a community `url` and returns the group itself — name, description, member count, rules, creation date. `GET /v1/twitter/community/tweets` (1cr) returns what has been posted inside it. Both take the community URL, and neither paginates.

**AI search.** `GET /v1/twitter/ai-search` (5cr) takes a plain-English `query` and returns a written answer, the X posts cited as sources, and how many searches the model ran to get there. Narrow it with `from_handles`, `exclude_handles`, `from_date`, and `to_date`.

**The composite.** `GET /v1/twitter/profile/full` (5cr) fans out to the profile and recent-posts endpoints in parallel and returns the unified author, the post list, and computed metrics — average engagement rate, posting cadence with the window it was measured over, the top post, and the format mix. `posts` sets how many recent tweets to average over (1-100, default 25), and `include=computed` drops the raw `posts[]` to save payload.

```bash
curl "https://www.socialcrawl.dev/v1/twitter/profile/full?handle=elonmusk&posts=50" \
  -H "x-api-key: sc_your_api_key_here"
```

Reaching further back than 100 tweets [#reaching-further-back-than-100-tweets]

`user/tweets` returns **one page and one page only** — up to 100 recent tweets, with no cursor to follow. This is the constraint most integrations hit first, and there are two ways past it:

* **`GET /v1/twitter/ai-search`** answers questions that would otherwise need a deep timeline walk: what an account said about a topic last week, who was arguing about a launch, which posts cited a claim. It searches rather than paginates, and `from_date` / `to_date` bound the period. 5cr a call.
* **[`/v1/search/everywhere`](/docs/search/everywhere.md)** includes X as a source (named `twitter-ai-search` there, not `twitter`) alongside the other networks, if the question is cross-platform rather than X-specific.

<Callout>
  The profile leg is the only critical leg on 

  `profile/full`

  . If the tweets cannot be fetched you still get a 

  `200`

   with the profile and null post-dependent metrics rather than an error, and every leg's outcome is reported in 

  `legs[]`

  . Check 

  `legs[]`

   before you treat a null cadence as a quiet account.
</Callout>

Endpoints [#endpoints]

<PlatformEndpoints platform="twitter" />

What should I know about Twitter/X data? [#what-should-i-know-about-twitterx-data]

* All endpoints use `GET` method with query parameters
* Authentication via `x-api-key` header
* Responses follow the unified SocialCrawl schema
* `profile`, `user/tweets`, and `profile/full` take a `handle` (no `@`); `tweet`, `tweet/transcript`, `community`, and `community/tweets` take a `url`; `ai-search` takes `query`
* `user/tweets`, `community/tweets`, and `ai-search` each return a single result set with no cursor. The one exception is `profile/full`, which accepts a `cursor` to deepen its post window
* `trim=true` on `user/tweets` and `tweet` returns a lighter payload at the same price

Official Twitter/X Resources [#official-twitterx-resources]

* [X API Documentation](https://developer.x.com/en/docs) — Official X developer platform
* [X API Access Levels](https://developer.x.com/en/docs/twitter-api/getting-started/about-twitter-api) — API tiers and access