# xfetch Agent Context

xfetch is a developer-facing X/Twitter data API for common public read workflows and dashboard-configured webhook account monitoring. It is designed for search and social listening, AI/LLM data pipelines, profile and account intelligence, audience and relationship graph analysis, tweet context analysis, and trend or market research.

## API Layers

- Start new integrations with `/v1`; it is the recommended product API.
- `Basic Reads`: direct read endpoints for familiar search, user, tweet, graph, list, community, and trend data.
- `Enriched Reads`: read-shaped endpoints that add normalized objects or richer response modes around a core resource.
- `Workflow APIs`: aggregated endpoints for jobs such as profile intelligence, tweet context analysis, and conversation review.
- `/2` compatibility: Basic Reads migration layer with official-style paths, query names, and response envelopes where supported. xfetch credit metadata is returned in response headers.
- `/v1` uses xfetch-owned parameters. Paginated endpoints use opaque `next_token`; recent search, trends, and graph `mode=ids` expose endpoint-specific `limit`; continuation-only endpoints do not expose `limit`.

## Authentication

Send customer API keys as Bearer tokens:

```http
Authorization: Bearer <api_key>
```

## Credits

- Free signup grants 1,000 credits for new users.
- Single-object lookups cost 1 credit.
- Collection endpoints cost 1 base credit plus 1 credit per returned primary item.
- Dedicated `/v1` workflow keys use value-tier rules: `search.enriched` is 2 base + 2 credits per returned tweet, `profile.lookup` is 2 base + 1 credit per recent tweet, and `tweet.context` is 3 base + 1 credit per quote or retweeter. Graph IDs cost 1 base + 1 credit per 20 IDs.
- Failed validation, auth failures, insufficient credits, rate limits, service-side failures, and internal failures do not charge users.
- `/v1` returns credit metadata in `meta.credits`.
- `/2` returns credit metadata in response headers.

## Basic Reads Mapping: `/v1` to `/2`

The `/v1` Basic layer covers the supported `/2` compatibility capabilities. Naming differs where `/v1` uses product-owned paths or query names.

- Recent search: GET /v1/search/recent maps to GET /2/tweets/search/recent. Use /v1 for xfetch-owned limit and pagination names; use /2 for migration-compatible query names.
- User by username: GET /v1/users/by-username/:username maps to GET /2/users/by/username/:username. Both layers support direct username lookup with layer-specific path naming.
- User by id: GET /v1/users/:id maps to GET /2/users/:id. Both layers support direct user lookup by ID.
- Users by ids: GET /v1/users?ids=... maps to GET /2/users?ids=.... Both layers support batch user lookup with comma-separated IDs.
- User tweets: GET /v1/users/:id/tweets maps to GET /2/users/:id/tweets. Use /v1 for normalized tweet fields and xfetch pagination names.
- Followers: GET /v1/users/:id/followers?mode=ids maps to GET /2/users/:id/followers. The Basic /v1 mapping recommends IDs mode for high-volume graph reads.
- Following: GET /v1/users/:id/following?mode=ids maps to GET /2/users/:id/following. The Basic /v1 mapping recommends IDs mode for high-volume graph reads.
- Tweet by id: GET /v1/tweets/:id maps to GET /2/tweets/:id. Both layers support direct tweet lookup by ID.
- Tweets by ids: GET /v1/tweets?ids=... maps to GET /2/tweets?ids=.... Both layers support batch tweet lookup with comma-separated IDs.
- Quote tweets: GET /v1/tweets/:id/quotes maps to GET /2/tweets/:id/quote_tweets. Use /v1 for product naming; /2 keeps the official-compatible path.
- Retweeters: GET /v1/tweets/:id/retweeters maps to GET /2/tweets/:id/retweeted_by. Both layers expose users who retweeted the tweet with layer-specific names.
- List tweets: GET /v1/lists/:id/tweets maps to GET /2/lists/:id/tweets. Both layers support reading tweets from a list.
- List members: GET /v1/lists/:id/members maps to GET /2/lists/:id/members. Both layers support reading list members.
- List subscribers/followers: GET /v1/lists/:id/subscribers maps to GET /2/lists/:id/followers. The /v1 path uses product naming while /2 keeps the official-compatible followers path.

## Enriched Reads

- GET /v1/search/recent/enriched
- GET /v1/users/:id/followers?mode=profiles
- GET /v1/users/:id/following?mode=profiles
- GET /v1/communities/:id/tweets

## Workflow APIs

- GET /v1/profiles/:id
- GET /v1/profiles/by-username/:username
- GET /v1/tweets/:id/context
- GET /v1/tweets/:id/conversation

## Public `/v1` Endpoints

- GET /v1/trends — see /docs/api-reference#v1-trends
- GET /v1/search/recent — see /docs/api-reference#v1-search-recent
- GET /v1/users/:id — see /docs/api-reference#v1-users-id
- GET /v1/users/by-username/:username — see /docs/api-reference#v1-users-by-username-username
- GET /v1/users?ids=... — see /docs/api-reference#v1-users-ids
- GET /v1/users/:id/tweets — see /docs/api-reference#v1-users-id-tweets
- GET /v1/users/:id/tweets/replies — see /docs/api-reference#v1-users-id-tweets-replies
- GET /v1/users/:id/media — see /docs/api-reference#v1-users-id-media
- GET /v1/users/:id/followers?mode=ids|profiles — see /docs/api-reference#v1-users-id-followers-mode-ids-profiles
- GET /v1/users/:id/verified-followers — see /docs/api-reference#v1-users-id-verified-followers
- GET /v1/users/:id/following?mode=ids|profiles — see /docs/api-reference#v1-users-id-following-mode-ids-profiles
- GET /v1/tweets/:id — see /docs/api-reference#v1-tweets-id
- GET /v1/tweets?ids=... — see /docs/api-reference#v1-tweets-ids
- GET /v1/tweets/:id/quotes — see /docs/api-reference#v1-tweets-id-quotes
- GET /v1/tweets/:id/retweeters — see /docs/api-reference#v1-tweets-id-retweeters
- GET /v1/tweets/:id/conversation — see /docs/api-reference#v1-tweets-id-conversation
- GET /v1/lists/:id/tweets — see /docs/api-reference#v1-lists-id-tweets
- GET /v1/lists/:id/members — see /docs/api-reference#v1-lists-id-members
- GET /v1/lists/:id/subscribers — see /docs/api-reference#v1-lists-id-subscribers
- GET /v1/communities/:id — see /docs/api-reference#v1-communities-id
- GET /v1/communities/search — see /docs/api-reference#v1-communities-search
- GET /v1/search/recent/enriched — see /docs/api-reference#v1-search-recent-enriched
- GET /v1/profiles/:id — see /docs/api-reference#v1-profiles-id
- GET /v1/profiles/by-username/:username — see /docs/api-reference#v1-profiles-by-username-username
- GET /v1/tweets/:id/context — see /docs/api-reference#v1-tweets-id-context
- GET /v1/communities/:id/tweets — see /docs/api-reference#v1-communities-id-tweets
- GET /v1/communities/:id/members — see /docs/api-reference#v1-communities-id-members
- GET /v1/communities/:id/moderators — see /docs/api-reference#v1-communities-id-moderators

## Public `/2` Endpoints

- GET /2/tweets/search/recent
- GET /2/users/by/username/:username
- GET /2/users/:id/tweets
- GET /2/users/:id/followers
- GET /2/users/:id/following
- GET /2/users/:id
- GET /2/users?ids=...
- GET /2/tweets/:id/retweeted_by
- GET /2/tweets/:id/quote_tweets
- GET /2/tweets/:id
- GET /2/tweets?ids=...
- GET /2/lists/:id/tweets
- GET /2/lists/:id/members
- GET /2/lists/:id/followers

## `/v1` Item Shapes

User object fields: `id`, `username`, `name`, `description`, `location` (optional), `created_at` (ISO 8601), `verified` (boolean), `protected` (boolean), `profile_image_url`, `follower_count`, `following_count`, `tweet_count`, `media_count` (optional).

Tweet object fields: `id`, `text`, `author_id`, `created_at` (ISO 8601), `lang`, `like_count`, `retweet_count`, `reply_count`, `quote_count`, `bookmark_count`, `is_quote_status` (boolean), `quoted_tweet_id` (optional), `entities` (`{ hashtags: string[], urls: string[], mentions: string[] }`), `media` (optional array of `{ type, url }` — video variant URLs and bitrates are intentionally not exposed).

Tweet context (`/v1/tweets/:id/context`) returns: `{ tweet, author, quotes, retweeters }`.

Enriched search (`/v1/search/recent/enriched`) returns `{ tweets, authors }`. `authors` is deduplicated by `id`, so its length is the number of unique authors on the page and may be smaller than `tweets.length`; join with `tweet.author_id`.

Trends (`/v1/trends`) returns ranked trends for a WOEID (default `1` = worldwide).

Conversation (`/v1/tweets/:id/conversation`) returns the paginated reply thread. The focal tweet itself is **not** included in `data`; fetch it separately via `/v1/tweets/:id` if you need both. Pages may contain descendant replies (replies of replies) alongside direct replies.

Graph endpoints (`/v1/users/:id/followers`, `/v1/users/:id/following`) support `mode=ids` (returns `{ id }` only) or `mode=profiles` (returns full enriched user objects, default).

Graph `mode=ids` returns `{ id }` objects and supports `limit` up to 5000 for large paginated graph reads.

## Examples

```http
GET /v1/search/recent/enriched?query=xfetch
```

```http
GET /v1/profiles/by-username/:username
```

```http
GET /v1/tweets/:id/context
```

```http
GET /v1/communities/:id/tweets
```

```http
GET /2/tweets/search/recent?query=xfetch&max_results=20
```

## Pagination

- `/v1` paginated endpoints use `next_token`.
- `/v1` exposes `limit` only where page size can be honored without dropping items: recent search (default 20, max 20), trends (default 20, max 100), and graph `mode=ids` (default 200, max 5000).
- `/2` paginated endpoints use official-compatible pagination query names where supported.
- Public pagination tokens are opaque. Do not parse or persist assumptions about token internals.

## Public Safety Boundaries

- xfetch supports public read workflows and dashboard-configured account monitoring in the current product scope.
- There are no write actions such as posting, liking, reposting, following, or DMs.
- Public docs, API responses, playground output, and agent context should describe xfetch capabilities, not internal implementation details.

## Links

- /llms-full.txt - Full agent-readable xfetch context
- /openapi.json - OpenAPI 3.x public API contract
- /docs - Human-readable docs
- /docs/api-reference - API reference
- /pricing - Credits and pricing
- /legal/terms - Terms
- /legal/privacy - Privacy
- /legal/refund - Refund policy